Skip to main content
Glama
filter-mcp-server

filter-mcp-server

by chohirin

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

filter-naive

Exact Set / Hash Table

Exact membership baseline

filter-bloom

Bloom Filter

Memory-efficient approximate membership filter

filter-counting-bloom

Counting Bloom Filter

Bloom Filter with deletion support

filter-cuckoo

Cuckoo Filter

Fingerprint-based approximate filter

filter-surf

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(items)

Build filter from dataset

insert(x)

Insert a key

contains(x)

Membership query

delete(x)

Delete a key if supported

range_query(lo, hi)

Range query

prefix_query(prefix)

Prefix query

memory_usage()

Return estimated memory usage

false_positive_rate()

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.benchmark

Run the smoke tests:

PYTHONPATH=src python -m unittest discover -s tests
$env:PYTHONPATH='src'; python -m unittest discover -s tests

Notes

  • filter-naive is 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 Set

Flow Description

  1. The LLM sends an MCP tool request.

  2. mcp_server.py exposes the common ADT-style tools.

  3. registry.py selects the requested filter implementation.

  4. The selected filter processes the query.

  5. 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 tools
buildD

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

    B3.1/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    9 tools is well-scoped for a filter server, covering initialization, insertion, deletion, queries, and statistics without being excessive or sparse.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      8
      59 npm
      15
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Data 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.
      9
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for hunting bugs in Python functions via adversarial input generation and minimized regression tests.
      MIT