Anythingllm Mcp Gateway

---

module_type: gateway status: active protocol: mcp primary_capability: semantic_memory requires: anythingllm works_with: ai_agents, antigravity, mcp_clients last_verified: 2026-09-05

AnythingLLM Semantic Memory Gateway MCP Server 🧠

CI Test Suite Go Version License: MIT MCP Server Status: Active

High-performance Go-based Model Context Protocol (MCP) server for AnythingLLM semantic memory integration (TheNovaNodes/anythingllm-mcp-gateway). Provides AI agents with hybrid search (dense vector embeddings + lexical FTS5 BM25), reciprocal rank fusion (RRF), adaptive token budgeting, and multi-tenant organization isolation.

---

🛠️ Exposed MCP Tools

The gateway exposes 3 high-level semantic memory tools:

• search_memory
  FTS5-First hybrid search querying AnythingLLM vector indices and local FTS5 lexical storage, fusing results with Reciprocal Rank Fusion (RRF), exact match boosting, and context assembly. Features candidate workspace pruning to prevent thundering herd timeouts across large multi-project clusters.
  Arguments:
  — query (string, required): The search text or question.
  — top_k (int, optional): Maximum number of passages to return (default: 5, max: 25).
  — workspace (string, optional): Target AnythingLLM workspace slug (defaults to automatic FTS5-First candidate routing).
  — expand_context (bool, optional): Expand matching passages to full surrounding paragraphs.
  — max_token_budget (int, optional): Token budget limit; results are trimmed on sentence boundaries.
  — tier (string, optional): Memory tier filter (episodic, semantic, procedural).
  — vector_weight (float, optional): Weight multiplier for vector retrieval layer in RRF (default: 1.0).
  — lexical_weight (float, optional): Weight multiplier for lexical FTS5 layer in RRF (default: 1.0).
  — min_vector_similarity (float, optional): Cosine similarity cutoff for pure-vector hits (default: 0.55).
  — max_context_chars (int, optional): Maximum characters for paragraph context expansion (default: 4000).
  — group_by (string, optional): Result grouping strategy (chunk or document, default: chunk).

• get_document
  Retrieves full raw document text directly from the local lexical SQLite index by document ID (<1ms latency, zero HTTP overhead). Automatically reassembles chunked documents into monolithic content.
  Arguments:
  — doc_id (string, required): Unique document identifier or file path.
  — workspace (string, optional): Target workspace slug filter.
  — max_chars (int, optional): Truncation limit in characters (default: 20000).

• gateway_health
  Diagnostics probe that verifies AnythingLLM REST API reachability, executes a live vector search probe, tests lexical database integrity, and reports operational status.
  Arguments: None.

---

⚡ Key Features

• Semantic Document Chunking & Windowing: Autonomous sliding-window tokenizer and chunker (512 tokens with 64-token overlap) preserving paragraph structure and attaching granular chunk metadata (chunk_index, total_chunks, parent_doc_id) for high-precision retrieval without context dilution.
• Multi-Tenant Organization Isolation: Filters candidates by allowed organizational scope (MG_ALLOWED_ORGS) before RRF fusion, preventing data leakage across distinct projects.
• FTS5 Morphological Stemming & Wildcards: Intelligent query expansion generating exact tokens, prefix wildcards (word*), and morphological stems for Russian inflections and English plurals/tenses, dramatically boosting lexical recall.
• Hybrid Synergy Multiplier: Automatically amplifies the rank score (+25% bonus) of documents corroborated by both vector semantic and lexical FTS5 layers.
• Smart Workspace Candidate Routing: Pre-filters candidate workspaces dynamically using lexical matches and query-token slug heuristics to prevent thundering herd timeouts across dozens of workspaces.
• BM25 Compound Tokenizer: Advanced FTS5 query parser that splits camelCase, PascalCase, kebab-case, snake_case, and hyphenated terms (ChaCha20Poly1305, agent-vault) into exact sub-tokens.
• SQLite FTS5 Column Weighting: Applies custom BM25 column weights (title=10.0, path=5.0, content=1.0) to give document titles priority over long body text.
• Vector Drift Sanitization: Filters out orthogonal vector noise (distance $\ge 0.85$ or score 1.0 distance inversion anomalies) before rank fusion.
• Exact RRF Boost: Adds score-based rank bonuses (+0.02 to +0.03) for high-confidence BM25 hits and exact title/path substring matches.
• Adaptive Token Budgeting: Trims retrieved passages on natural sentence and paragraph boundaries when max_token_budget is set.
• Context Assembly & 48-Token Snippets: Returns rich 48-token context snippets with highlight markers and expands snippet hits to full surrounding paragraph context for coherent agent reasoning.
• Ultra-Low Overhead: Written in pure Go (Go 1.25) with zero CGO dependencies (modernc.org/sqlite). Consumes ~13 MB RAM in production.

---

🚀 Quick Start & Building

Prerequisites

• Go 1.25 or higher

Build Binary

git clone https://github.com/TheNovaNodes/anythingllm-mcp-gateway.git
cd anythingllm-mcp-gateway
make build

The compiled binaries will be placed in ./bin/:

• bin/anythingllm-gateway — MCP stdio search server
• bin/anythingllm-sync — Autonomous background ETL sync daemon

Install System-wide

sudo cp bin/anythingllm-gateway /usr/local/bin/
sudo cp bin/anythingllm-sync /usr/local/bin/

Health Check (stdio smoke test)

anythingllm-gateway < /dev/null
anythingllm-sync -once

---

⚙️ Configuration & Environment Variables

• MG_ALM_BASE (or ANYTHINGLLM_BASE_URL)
  AnythingLLM REST API base endpoint.
  Default: http://127.0.0.1:3002/api/v1
• MG_API_KEY (or ANYTHINGLLM_API_KEY)
  AnythingLLM Bearer API key.
• MG_ALLOWED_ORGS
  Comma-separated list of organization slugs allowed for multi-tenant isolation (e.g. thenovanodes, thedoctormes-hue).
• MG_WORKSPACE (or MG_DEFAULT_WORKSPACE)
  Default workspace slug for search and storage.
  Default: default
• MG_LEXICAL_DB
  Optional path to SQLite database for FTS5 lexical search.
  Default: ./lexical.db (auto-detects /opt/projects/TheNovaNodes/ops/shared/anythingllm-sync/lexical.db if running on host cluster)
• MG_LEXICAL_MIN_SCORE
  Minimum lexical score threshold (float, default: 0.0).
• MG_MIN_VECTOR_SIMILARITY
  Minimum cosine similarity threshold for pure-vector candidates without lexical corroboration (float, default: 0.55). Discards out-of-domain noise.
• MG_VECTOR_SCORE_THRESHOLD
  Minimum AnythingLLM vector search score threshold (float, default: 0.13).
• MG_RRF_K
  Reciprocal Rank Fusion smoothing constant (int, default: 60).
• MG_VECTOR_MAX_INFLIGHT
  Maximum concurrent vector API calls to protect the AnythingLLM instance (default: 4).
• MG_SEARCH_TIMEOUT
  Search request timeout in seconds (default: 10).

---

🔌 MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Antigravity, or mcp-router):

{
  "mcpServers": {
    "anythingllm-gateway": {
      "command": "/usr/local/bin/anythingllm-gateway",
      "args": [],
      "env": {
        "MG_ALM_BASE": "http://127.0.0.1:3002/api/v1",
        "MG_API_KEY": "YOUR_API_KEY_HERE",
        "MG_WORKSPACE": "default"
      }
    }
  }
}

---

🧪 Testing

Run the full Go test suite with data race detection:

make test

Generate a code coverage report:

make coverage

---

📄 License

MIT License — see LICENSE for details.