Filter MCP Server

What chohyerinn/filter-mcp-server MCP server does

The chohyerinn/filter-mcp-server MCP server provides several independently selectable data-structure implementations behind a shared MCP interface. It includes an exact hash-set baseline plus approximate filters: Bloom, Counting Bloom, Cuckoo, and a simplified SuRF implementation.

The project is intended for comparing behavior under the same workload. Its example scenario is keyword dictionary management, including autocomplete, keyword lookup, blocked-word checks, and dictionary membership tests. The comparison considers membership accuracy, false positives, estimated memory use, local query latency, mutation support, and prefix or range queries.

The SuRF implementation is explicitly simplified and educational. The repository describes the project as an experimentation and comparison tool, not as a production optimization package.

How it works

An MCP client sends a tool request to the selected server. The MCP layer exposes a common ADT-style interface, a registry chooses the filter implementation, and the selected class processes the request before returning the result.

Available operations are:

• build(items) to initialize a filter from a dataset
• insert(x) to add a key
• contains(x) to test membership
• delete(x) to remove a key when supported
• range_query(lo, hi) for range lookups where supported
• prefix_query(prefix) for prefix lookups where supported
• memory_usage() for estimated memory consumption
• false_positive_rate() for false-positive measurement

The structures do not provide identical behavior. Bloom filters support approximate membership but not deletion, while Counting Bloom and Cuckoo filters support deletion. The simplified SuRF supports prefix and range queries but not deletion. The exact-set baseline avoids false positives and supports the full query and mutation behavior described by the project.

Setup and configuration

The repository provides separate Python entry points for each implementation. Claude Desktop can be configured with one or more MCP servers using these scripts:

{
  "mcpServers": {
    "filter-naive": {
      "command": "python",
      "args": ["src/filter_/filter_naive_server.py"]
    },
    "filter-bloom": {
      "command": "python",
      "args": ["src/filter_/filter_bloom_server.py"]
    },
    "filter-counting-bloom": {
      "command": "python",
      "args": ["src/filter_/filter_counting_bloom_server.py"]
    },
    "filter-cuckoo": {
      "command": "python",
      "args": ["src/filter_/filter_cuckoo_server.py"]
    },
    "filter-surf": {
      "command": "python",
      "args": ["src/filter_/filter_surf_server.py"]
    }
  }
}

Run the benchmark from the repository with PYTHONPATH=src python -m membership_filters.benchmark. The test suite can be run with PYTHONPATH=src python -m unittest discover -s tests. PowerShell equivalents are included in the README.

Tools and capabilities

The chohyerinn/filter-mcp-server MCP server keeps the tool names consistent across implementations, allowing the same dataset and queries to be sent to different structures. This supports side-by-side experiments with approximate membership, deletion behavior, prefix and range support, estimated memory, and false-positive measurements.

Benchmark results use fixed synthetic workloads and absent-query probes. Reported values include estimated memory from memory_usage(), measured false-positive rates from false_positive_rate(), and average local contains() latency. The repository distinguishes these measured benchmark outputs from its qualitative structure comparison.

Limitations and notes

Approximate filters trade reduced memory use for possible false positives or restricted operations. The README does not present the qualitative comparison table as a measured benchmark result. The simplified SuRF server should not be treated as a complete LOUDS-based production SuRF implementation.

The chohyerinn/filter-mcp-server MCP server is therefore best suited to controlled comparison, teaching, and local experimentation. Choose the exact-set server when false positives are unacceptable, and select an approximate implementation only when its operation and accuracy trade-offs fit the workload.