feat: add Anthropic LLM binding for API server + MCP server adapter#3028
Open
tonygil wants to merge 7 commits intoHKUDS:mainfrom
Open
feat: add Anthropic LLM binding for API server + MCP server adapter#3028tonygil wants to merge 7 commits intoHKUDS:mainfrom
tonygil wants to merge 7 commits intoHKUDS:mainfrom
Conversation
- Add 'anthropic' as a supported LLM_BINDING option in config.py and lightrag_server.py - Implement anthropic_model_complete wrapper using anthropic_complete_if_cache - Fix write_json to use temp file + atomic rename to avoid Windows Defender locking large JSON files mid-write Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds lightrag-mcp entry point — a thin MCP adapter that wraps the existing REST API as two tools (query, search) for use with Claude Desktop, Cursor, and any MCP-compatible client. Also changes the default query mode from 'mix' to 'local' for faster response times when callers don't specify a mode. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Hide mode/top_k behind LIGHTRAG_QUERY_MODE / LIGHTRAG_TOP_K env vars; retrieval tuning is an ops concern, not a caller concern - Make HTTP timeout configurable via LIGHTRAG_MCP_TIMEOUT (default 120s) - Rename `search` tool to `retrieve` to signal diagnostic intent - Raise McpError on 5xx and transport failures; return string on 4xx - Format references as [title](url), falling back to reference_id Also adds CONTEXT.md with domain glossary (Knowledge Graph, Query, Retrieve, MCP Server, Retrieval Mode). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
QueryParam is now a pure value object — field defaults are compile-time
constants, not os.getenv() calls. All env-based defaulting is centralised
in ConfigResolver (lightrag/query_config.py).
- lightrag/query_config.py: new module with QueryParam, ConfigResolver,
default_query_param()
- lightrag/base.py: re-exports QueryParam for backwards compatibility;
removes env-reading field defaults and unused imports
- CONTEXT.md: adds QueryParam and ConfigResolver glossary entries
Tests can now inject Query config via ConfigResolver(env={...}).query_param()
without mutating os.environ.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
… backends
Extracts the repeated workspace-path block from 5 file-based storage
__post_init__ methods into resolve_workspace() in shared_storage.py.
Before (repeated identically in each backend):
working_dir = self.global_config["working_dir"]
if self.workspace:
workspace_dir = os.path.join(working_dir, self.workspace)
else:
workspace_dir = working_dir
self.workspace = ""
os.makedirs(workspace_dir, exist_ok=True)
After (one call per backend):
workspace_dir, self.workspace = resolve_workspace(
self.global_config, self.workspace
)
Backends updated: JsonKVStorage, JsonDocStatusStorage,
NanoVectorDBStorage, NetworkXStorage, FaissVectorDBStorage.
Remote backends (Mongo, Postgres, Redis, etc.) are unchanged.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…elds Adding a field to QueryParam without adding it to QueryRequest is the common failure mode when the two models drift. This test catches it at CI time with a clear error message and documented exclusion list. Uses ast to parse QueryRequest field names without importing the module, avoiding the API auth chain that calls parse_args() in test context. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ision Warm-up (_warmup): on startup, GET /health to verify the LightRAG server is reachable before accepting MCP connections. Emits a warning (not a crash) so transient connectivity issues during rolling restarts don't block startup. Surfaces LIGHTRAG_API_URL misconfiguration immediately rather than on the first user query. ADR-0001: records that the MCP Server is intentionally a thin adapter and that query caching was considered and deferred (belongs in the REST API where cache invalidation can be wired to ingestion events, not in the MCP layer which has no visibility into Knowledge Graph changes). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds two features and a suite of architectural improvements developed
during a grilling session on the MCP server design.
New features
anthropicas a selectableLLM_BINDINGoption in the API server, wiring it throughconfig.pyandlightrag_server.pyto the existinglightrag/llm/anthropic.py.lightrag/mcp_server.py): A Model Context Protocoladapter exposing two tools to MCP-compatible clients (Claude Desktop, Cursor,
etc.):
query— LLM-synthesised answer from the Knowledge Graphretrieve— raw entities, relations, and chunks for diagnostic uselightrag/utils.py): Fixes a WindowsDefender file-locking issue on large JSON writes via temp file + atomic rename.
Architectural improvements
ConfigResolver(lightrag/query_config.py):QueryParamis now a purevalue object with no
os.getenv()calls at class definition time. All env-varreading is centralised in
ConfigResolver; tests inject config viaConfigResolver(env={...}).query_param()without mutatingos.environ.resolve_workspace(lightrag/kg/shared_storage.py): The repeatedworkspace path resolution block (
working_dir+makedirs) is extracted intoone helper used by all 5 file-based storage backends (
JsonKVStorage,JsonDocStatusStorage,NanoVectorDBStorage,NetworkXStorage,FaissVectorDBStorage).tests/test_query_param_parity.py):CI fails with a clear message if a field is added to
QueryParambut not toQueryRequest. Usesastto read field names without triggering the API authchain.
retrievetoolrenamed from
search;McpErrorraised on 5xx/transport failures; referencesformatted as
[title](url).GET /healthon MCP server startup surfacesmisconfiguration immediately rather than on the first user query.
that query caching (if ever needed) belongs in the REST API layer, not here.
CONTEXT.md: Domain glossary with canonical terms (Knowledge Graph, Query,Retrieve, MCP Server, Retrieval Mode, QueryParam, ConfigResolver).
Test plan
LLM_BINDING=anthropic+LLM_MODEL=claude-sonnet-4-6in.env,start server, confirm model responds
lightrag-mcp— confirm warm-up logs reachability of LightRAG serverqueryandretrievetoolsappear and return results
pytest tests/test_query_param_parity.pypasses offline🤖 Generated with Claude Code