Purpose
filter-mcp-server is a project that uses an MCP server and LLM tool calls to compare multiple approximate filter data structures. Approximate filters reduce memory usage by storing compressed summaries instead of full keys, but this introduces trade-offs such as false positives or limited operations. The project aims to compare the behavior of different filter structures under the same workload.
Main Capabilities
The project compares the following filters:
- Bloom filter
- Counting Bloom filter
- Cuckoo filter
- SuRF (simplified version)
It also includes an exact hash set server as a baseline comparison (filter-naive).
The comparison focuses on:
- Membership query accuracy
- False positive rate
- Insert and delete support
- Prefix and range query capabilities
All servers expose the same ADT-style interface through MCP tools so that testing can be done consistently.
Usage
The server simulates a keyword search system, applied to:
- Search autocomplete
- Blocked-word checking
- Dictionary membership testing
All filters use the same keyword dataset and queries to compare performance and behavior. All MCP servers provide the same tool set.
The project provides a theoretical/qualitative structure comparison table describing the expected qualitative behavior of each structure; this table is not measured benchmark results.
Measured results are located in docs/benchmark_results.md. The benchmark uses a fixed synthetic workload in src/membership_filters/benchmark.py, comparing all filters with the same build items and missing-query probes. The report includes: memory estimated via memory_usage(), false positive rate measured via false_positive_rate(), and average latency of local contains().
The benchmark can be run locally, and smoke tests can also be run. filter-naive is included as an exact baseline.
Example Claude Desktop MCP Configuration
The project provides an example Claude Desktop MCP configuration.
Process Description
- The LLM sends an MCP tool request.
- mcp_server.py exposes generic ADT-style tools.
- registry.py selects the requested filter implementation.
- The selected filter processes the query.
- Results are returned through the MCP server.
This design allows all filters to be tested through the same interface and workload.
Applicable Scenarios
Suitable for researchers and developers who need to learn, experiment with, or compare approximate filter data structures, especially in simulated scenarios such as keyword search, autocomplete, and blocked-word checking.
Limitations
The SuRF server is a simplified educational implementation, not a complete production-grade SuRF based on LOUDS. The project focuses on comparison and experimentation, not production optimization.
