filter-mcp-server
This server provides a unified interface for building, querying, and benchmarking approximate membership filter data structures, including Bloom Filter, Counting Bloom Filter, Cuckoo Filter, Simplified SuRF, and an exact hash-set baseline.
Build (
build): Initialize the filter from an initial dataset of strings, with optional configuration parameters.Insert (
insert): Add a single string key (unsupported by static structures).Contains (
contains): Check membership for a specific string key (may return false positives depending on filter type).Delete (
delete): Remove a key if the filter supports deletion (e.g., Counting Bloom, Cuckoo; not standard Bloom or SuRF).Range query (
range_query): Lexicographic half-open range query (lo <= key < hi), unsupported by point-only filters.Prefix query (
prefix_query): Query for keys sharing a given prefix, unsupported by point-only filters.Memory usage (
memory_usage): Retrieve estimated memory footprint and bits-per-item metrics.False positive rate (
false_positive_rate): Get theoretical and empirically measured false positive rates.Reset (
reset): Clear all data and reinitialize the filter, optionally with a new configuration.
The consistent ADT-style interface makes it easy to compare the behavior and performance trade-offs across different filter implementations.
Approximate Filters using MCP Servers
Overview
This project compares several approximate filter data structures using MCP servers and LLM tool calls.
Approximate filters reduce memory usage by storing compressed summaries instead of full keys.
Because of this trade-off, some filters may return false positives or support limited operations.
The project compares:
Bloom Filter
Counting Bloom Filter
Cuckoo Filter
SuRF (Simplified Version)
An exact hash-set server is also included as a baseline for comparison.
Related MCP server: mcp-compress
Implemented MCP Servers
MCP Server | Data Structure | Description |
| Exact Set / Hash Table | Exact membership baseline |
| Bloom Filter | Memory-efficient approximate membership filter |
| Counting Bloom Filter | Bloom Filter with deletion support |
| Cuckoo Filter | Fingerprint-based approximate filter |
| Simplified SuRF | Approximate prefix/range filter |
Project Goal
The goal of this project is to compare how different filter structures behave under the same workload.
The comparison focuses on:
membership query accuracy
false positive rate
memory usage
query latency
insertion and deletion support
prefix and range query capability
All servers expose the same ADT-style interface through MCP tools so that they can be tested consistently.
Scenario
Search Keyword Dictionary Management
The servers simulate a keyword search system.
Examples:
search autocomplete
keyword lookup
blocked-word checking
dictionary membership testing
The same keyword dataset and queries are used across all filters to compare performance and behavior.
ADT
All MCP servers provide the following tools:
Tool | Description |
| Build filter from dataset |
| Insert a key |
| Membership query |
| Delete a key if supported |
| Range query |
| Prefix query |
| Return estimated memory usage |
| Measure false positive rate |
Theoretical / Qualitative Structure Comparison
Structure | False Positives | Delete Support | Prefix/Range Query | Memory Efficiency |
Exact Set | No | Yes | Yes | Low |
Bloom Filter | Yes | No | No | Very High |
Counting Bloom Filter | Yes | Yes | No | High |
Cuckoo Filter | Yes | Yes | No | High |
Simplified SuRF | Yes | No | Yes | Medium |
This table describes the expected qualitative behavior of each structure. It is not a measured benchmark result.
Benchmark Results
Measured results are available in docs/benchmark_results.md.
The benchmark uses fixed synthetic workloads from src/membership_filters/benchmark.py and compares all filters with the same build items and absent-query probes. It reports estimated memory from memory_usage(), measured false positive rate from false_positive_rate(), and average local contains() latency.
Run it locally:
PYTHONPATH=src python -m membership_filters.benchmark$env:PYTHONPATH='src'; python -m membership_filters.benchmarkRun the smoke tests:
PYTHONPATH=src python -m unittest discover -s tests$env:PYTHONPATH='src'; python -m unittest discover -s testsNotes
filter-naiveis included as the exact baseline.The SuRF server is a simplified educational implementation, not a full LOUDS-based production SuRF.
The project focuses on comparison and experimentation rather than production optimization.
Example Claude Desktop MCP Configuration
{
"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"]
}
}
}System Flow
Claude / LLM
↓
MCP Tool Call
↓
mcp_server.py
↓
registry.py
↓
Selected Filter Class
↓
Bloom / Counting Bloom / Cuckoo / SuRF / Exact SetFlow Description
The LLM sends an MCP tool request.
mcp_server.pyexposes the common ADT-style tools.registry.pyselects the requested filter implementation.The selected filter processes the query.
The result is returned back through the MCP server.
This design allows all filters to be tested through the same interface and workload.
Repository Structure
src/
├── filter_/
│ ├── filter_naive_server.py
│ ├── filter_bloom_server.py
│ ├── filter_counting_bloom_server.py
│ ├── filter_cuckoo_server.py
│ └── filter_surf_server.py
│
└── membership_filters/
├── base.py
├── hashing.py
├── mcp_server.py
├── registry.py
└── filters/Available Tools
9 toolsbuildD
Build this filter from an initial string dataset.
Inputs: items (required), config.
containsC
Point membership query for one string key.
Inputs: x (required).
deleteC
Delete one key if the structure supports deletion.
Inputs: x (required).
false_positive_rateC
Return theoretical and measured false positive rate.
Inputs: absent_items.
insertC
Insert one string key. Static structures return a standard unsupported response.
Inputs: x (required).
memory_usageB
Return pure-structure memory estimate and bits per item.
Inputs: no named parameters.
prefix_queryD
Prefix query. Unsupported point-only filters return N/A.
Inputs: prefix (required).
range_queryA
Lexicographic half-open range query: lo <= key < hi. Unsupported point-only filters return N/A.
Inputs: lo (required), hi (required).
resetB
Clear all data and reinitialize with optional new config.
After reset, the filter is empty; use build() or insert() to add data again.
Inputs: config.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a distinct purpose: building from dataset, insertion, membership query, deletion, statistics, memory usage, and two specific query types. No overlap in functionality.
All tool names follow a consistent pattern of lowercase verbs or verb-noun descriptions with underscores for compound names (e.g., false_positive_rate, prefix_query). No mixing of styles.
9 tools is well-scoped for a filter server, covering initialization, insertion, deletion, queries, and statistics without being excessive or sparse.
The tool surface covers all essential operations for a filter data structure: building, inserting, deleting, membership testing, multiple query types, and memory/error rate stats. Missing features are structure-dependent and handled gracefully with standard responses.
Maintenance
Related MCP Connectors
Benchmark MCP tool selection with metadata-only routing, collision, abstention, and holdout checks.
SigRank benchmark MCP: cascade metrics, leaderboard, operator profiles, simulation, diagnostics.
Papers (ML research) MCP.
Closed-source remote MCP: model benchmarks, costs, HN signals, tech registry.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables users to query, compare, and synthesize responses from multiple local and cloud LLMs simultaneously using existing subscriptions. It provides tools for parallel model evaluation, consensus polling with an LLM-as-judge, and response synthesis across different model providers.859 npm15MIT
- AlicenseAqualityDmaintenanceData compression MCP server with auto-algorithm selection (gzip, brotli, deflate). 7 tools for compress, decompress, analyze, store, retrieve, list, and stats. Achieves 60x compression on docs, 30x on SQL. Lossless round-trip verified. Zero dependencies.93MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for hunting bugs in Python functions via adversarial input generation and minimized regression tests.MIT
- AlicenseAqualityBmaintenanceMCP server exposing a "run" tool that benchmarks agent-memory backends and returns a reproducible JSON report.137 PyPI2Apache 2.0