mcp-knowledge-graph 0.1.0__py3-none-any.whl

mcp_knowledge_graph-0.1.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: mcp-knowledge-graph
+Version: 0.1.0
+Summary: Neo4j knowledge graph retrieval MCP server
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.6.0
+Requires-Dist: neo4j>=5.0.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: twine>=6.2.0
+Description-Content-Type: text/markdown
+
+# Neo4j Knowledge Graph MCP Server
+
+MCP server for enterprise knowledge graph retrieval over Neo4j. Client LLM generates Cypher; this server provides schema resources, validation, and read-only execution.
+
+> 中文详细说明请参阅：[docs/知识图谱检索MCP服务说明.md](docs/知识图谱检索MCP服务说明.md)
+
+## Architecture
+
+- **10 Resources**: 7 static (schema, constraints, conventions, semantics, glossary, patterns, safety) + 3 dynamic (stats, samples, indexes)
+- **7 Tools**: `get_graph_context`, `get_cypher_prompt`, `validate_cypher`, `execute_cypher`, `explain_cypher`, `resolve_entity`, `refresh_graph_stats`
+- **4 Prompts**: `generate_cypher_query`, `refine_cypher_query`, `explain_query_result`, `decompose_complex_question`
+
+Context Tools (`get_graph_context_tool`, `get_cypher_prompt_tool`) provide the same schema context as Resources/Prompts for **Tools-only** MCP clients that do not support `resources/read` or `prompts/get`.
+
+## Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install mcp neo4j pyyaml pydantic pydantic-settings
+```
+
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `NEO4J_URI` | `bolt://localhost:7687` | Neo4j Bolt URI |
+| `NEO4J_USER` | `neo4j` | Neo4j user |
+| `NEO4J_PASSWORD` | `password` | Neo4j password |
+| `NEO4J_DATABASE` | `neo4j` | Neo4j database |
+| `MCP_TRANSPORT` | `stdio` | `stdio` \| `streamable-http` \| `sse` |
+| `MCP_HOST` | `127.0.0.1` | HTTP/SSE bind host |
+| `MCP_PORT` | `8000` | HTTP/SSE bind port |
+| `MCP_SSE_PATH` | `/sse` | SSE endpoint path |
+| `MCP_STREAMABLE_HTTP_PATH` | `/mcp` | Streamable HTTP endpoint path |
+
+Copy `.env.example` to `.env` and adjust as needed.
+
+## Import graph data
+
+From ontology_system:
+
+```bash
+curl -o graph-import.cypher http://localhost:8183/graph/export/cypher
+cypher-shell -u neo4j -p password -f graph-import.cypher
+```
+
+## Run MCP server
+
+### stdio（默认，Cursor 子进程模式）
+
+```bash
+PYTHONPATH=. python -m src.server
+```
+
+### streamable-http（推荐 HTTP 模式）
+
+```bash
+PYTHONPATH=. python -m src.server --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+Endpoint: `http://127.0.0.1:8000/mcp`
+
+### SSE
+
+```bash
+PYTHONPATH=. python -m src.server --transport sse --host 127.0.0.1 --port 8000
+```
+
+Endpoint: `http://127.0.0.1:8000/sse`
+
+### 局域网访问（Cherry Studio 等远程客户端）
+
+绑定 `0.0.0.0` 时，必须配置允许的 Host 头，否则会出现 `421 Misdirected Request`：
+
+```bash
+PYTHONPATH=. python -m src.server \
+  --transport streamable-http \
+  --host 0.0.0.0 \
+  --port 7688 \
+  --allowed-host 192.168.0.18:7688
+```
+
+或使用环境变量：
+
+```bash
+export MCP_ALLOWED_HOSTS=192.168.0.18:7688
+PYTHONPATH=. python -m src.server --transport streamable-http --host 0.0.0.0 --port 7688
+```
+
+局域网临时调试可加 `--disable-transport-security`（不推荐生产环境）。
+
+> 绑定 `0.0.0.0` 前请确认网络访问控制；生产环境建议置于反向代理之后。
+
+## Cursor MCP configuration
+
+### stdio（command）
+
+```json
+{
+  "mcpServers": {
+    "knowledge-graph": {
+      "command": "/path/to/mcp_knowledge_graph/.venv/bin/python",
+      "args": ["-m", "src.server"],
+      "cwd": "/path/to/mcp_knowledge_graph",
+      "env": {
+        "PYTHONPATH": "/path/to/mcp_knowledge_graph",
+        "NEO4J_URI": "bolt://192.168.0.18:7687",
+        "NEO4J_PASSWORD": "password"
+      }
+    }
+  }
+}
+```
+
+### streamable-http（url，含 Cherry Studio）
+
+先启动服务（局域网需 `--allowed-host`）：
+
+```bash
+PYTHONPATH=. python -m src.server \
+  --transport streamable-http \
+  --host 0.0.0.0 \
+  --port 7688 \
+  --allowed-host 192.168.0.18:7688
+```
+
+Cherry Studio JSON 配置：
+
+```json
+{
+  "mcpServers": {
+    "knowledge-graph": {
+      "url": "http://192.168.0.18:7688/mcp"
+    }
+  }
+}
+```
+
+也可通过 args 指定 transport：
+
+```json
+{
+  "mcpServers": {
+    "knowledge-graph": {
+      "command": "/path/to/mcp_knowledge_graph/.venv/bin/python",
+      "args": ["-m", "src.server", "--transport", "streamable-http", "--port", "8000"],
+      "cwd": "/path/to/mcp_knowledge_graph",
+      "env": {
+        "PYTHONPATH": "/path/to/mcp_knowledge_graph"
+      }
+    }
+  }
+}
+```
+
+## Verify pipeline
+
+```bash
+PYTHONPATH=. python scripts/verify_import_pipeline.py
+```
+
+## Tests
+
+```bash
+PYTHONPATH=. pytest tests/ -v
+```
+
+## Workflow
+
+### Full MCP client (Resources + Prompts)
+
+1. Client reads `graph://schema`, `graph://ontology-constraints`, `graph://query-patterns`
+2. Optional: `resolve_entity` for name disambiguation
+3. Client LLM uses `generate_cypher_query` prompt to produce Cypher JSON
+4. `validate_cypher` → `execute_cypher` → `explain_query_result`
+
+### Tools-only client
+
+1. `get_cypher_prompt_tool(question=...)` or `get_graph_context_tool(scope="core")`
+2. Optional: `resolve_entity` → pass result as `entity_hints`
+3. Platform LLM generates Cypher JSON from returned prompt fields
+4. `validate_cypher` → `execute_cypher` → platform LLM explains records

mcp_knowledge_graph-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+src/__init__.py,sha256=1XIYRnuNBChFD1Ma2mpbzzHeI7ppUhnNHhJmuR4EYyo,40
+src/cli.py,sha256=ltIh_mxqchbKZxT7GcHWGD14hgaesM2QkRKlC5f-OAM,7794
+src/config.py,sha256=6-AQ53eTwLYrqlZLep8hu4cmU8cawIN-pPzF-rKlMz0,1684
+src/neo4j_client.py,sha256=qu7P-3YaxEJMpHl-AZaZh7owkO3iNjQVzCDncygDmQs,8726
+src/ontology.py,sha256=trO4TXCTTxaYEP-cEXnvY7HVbczEtsbozcyeK7DOPtU,1785
+src/server.py,sha256=UlGWGuV0c2nkE_Sb5FeFyWPsdojFNXfzZnnrG-HFEEs,16868
+src/prompts/__init__.py,sha256=2mUG1nkJoFm0uNEQiW0rht3IWBVXLnSsnmMGcpooz50,25
+src/prompts/cypher_generation.py,sha256=kz74xEnoX0-PWbp8cuomDNu_TIYWgbvOG151RagOLqs,3887
+src/resources/__init__.py,sha256=ijnjmQlr8w6jwP1ijqKgpk4Ol__kueYpzj9VUc3J7JE,27
+src/resources/bundle.py,sha256=30epFKkvij4X8K2JvEiRgnPSOUGG3adLO9un928nqJo,3266
+src/resources/dynamic.py,sha256=ms9Y9Iu7hxonFN2HuX99Kh5HLdnXih7YI-u3UiaoFN8,1063
+src/resources/static.py,sha256=JUip6K3MLh9ggbtaPxaVILkUPM4ehS38BBzqry_6vQI,8451
+src/tools/__init__.py,sha256=Wl4h9y5FArRxkXUa-uLOBdI_d_WMjaBxJ-V0ttBcOgw,23
+src/tools/context.py,sha256=uKI1XNVL31LbAm6hZp5GnygJo5ulrpfo10eSN_hoopo,1680
+src/tools/execute.py,sha256=QgUfp47Y-P6SXPrwS2pm1n4Ialx5v-O5w9Rs1ueEMgA,2522
+src/tools/resolve.py,sha256=0Rqw30BaGsGj6vWc-BhEBecjYDK8ekK5RPOO_s5k0rw,1280
+src/tools/validate.py,sha256=IJXpZTq8B6YctKTFFl9Zb0NFreLOphwKjmbWVTU5OgU,5410
+mcp_knowledge_graph-0.1.0.dist-info/METADATA,sha256=tRjEO8lZogiA6Poj2WLwLLmKTUVe7cbGXL8VPS8XhYM,5393
+mcp_knowledge_graph-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mcp_knowledge_graph-0.1.0.dist-info/entry_points.txt,sha256=pKYU88e_nkrP1DeEmITBQO0rWGB9tDTcqLIsgKuKMGg,56
+mcp_knowledge_graph-0.1.0.dist-info/RECORD,,

mcp_knowledge_graph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_knowledge_graph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-knowledge-graph = src.server:main

src/__init__.py

@@ -0,0 +1 @@
+"""Neo4j knowledge graph MCP server."""

src/cli.py

@@ -0,0 +1,233 @@
+"""CLI 参数解析与 MCP 启动配置合并。"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from dataclasses import dataclass
+from typing import Literal
+
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+
+from src.config import VALID_TRANSPORTS, McpSettings, TransportType, mcp_settings
+
+logger = logging.getLogger(__name__)
+
+TransportName = Literal["stdio", "sse", "streamable-http"]
+
+
+@dataclass(frozen=True)
+class RunConfig:
+    transport: TransportType
+    host: str
+    port: int
+    sse_path: str
+    streamable_http_path: str
+    allowed_hosts: tuple[str, ...]
+    allowed_origins: tuple[str, ...]
+    disable_transport_security: bool
+
+
+def _split_csv(value: str | None) -> tuple[str, ...]:
+    if not value or not value.strip():
+        return ()
+    return tuple(item.strip() for item in value.split(",") if item.strip())
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Neo4j 知识图谱 MCP 服务",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=sorted(VALID_TRANSPORTS),
+        default=None,
+        help="MCP 传输协议：stdio（默认）、streamable-http、sse",
+    )
+    parser.add_argument(
+        "--host",
+        default=None,
+        help="HTTP/SSE 监听地址（默认 127.0.0.1）",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help="HTTP/SSE 监听端口（默认 8000）",
+    )
+    parser.add_argument(
+        "--sse-path",
+        dest="sse_path",
+        default=None,
+        help="SSE 端点路径（默认 /sse）",
+    )
+    parser.add_argument(
+        "--streamable-http-path",
+        dest="streamable_http_path",
+        default=None,
+        help="Streamable HTTP 端点路径（默认 /mcp）",
+    )
+    parser.add_argument(
+        "--allowed-host",
+        dest="allowed_hosts",
+        default=None,
+        help="允许的 Host 头，逗号分隔（如 192.168.0.18:7688 或 192.168.0.18:*）",
+    )
+    parser.add_argument(
+        "--allowed-origin",
+        dest="allowed_origins",
+        default=None,
+        help="允许的 Origin 头，逗号分隔（如 http://192.168.0.18:*）",
+    )
+    parser.add_argument(
+        "--disable-transport-security",
+        action="store_true",
+        default=None,
+        help="关闭 DNS rebinding 校验（局域网调试，不推荐生产）",
+    )
+    return parser
+
+
+def parse_cli_args(argv: list[str] | None = None) -> argparse.Namespace:
+    return _build_parser().parse_args(argv)
+
+
+def validate_transport(transport: str) -> TransportType:
+    if transport not in VALID_TRANSPORTS:
+        valid = ", ".join(sorted(VALID_TRANSPORTS))
+        raise ValueError(f"Unknown transport '{transport}'. Valid transports: {valid}")
+    return transport  # type: ignore[return-value]
+
+
+def build_run_config(
+    args: argparse.Namespace,
+    env: McpSettings | None = None,
+) -> RunConfig:
+    """合并配置：CLI 显式参数 > 环境变量 > 默认值。"""
+    env = env or mcp_settings
+    transport = validate_transport(args.transport if args.transport is not None else env.transport)
+    disable_security = (
+        args.disable_transport_security
+        if args.disable_transport_security is not None
+        else env.disable_transport_security
+    )
+    allowed_hosts = _split_csv(
+        args.allowed_hosts if args.allowed_hosts is not None else env.allowed_hosts
+    )
+    allowed_origins = _split_csv(
+        args.allowed_origins if args.allowed_origins is not None else env.allowed_origins
+    )
+    return RunConfig(
+        transport=transport,
+        host=args.host if args.host is not None else env.host,
+        port=args.port if args.port is not None else env.port,
+        sse_path=args.sse_path if args.sse_path is not None else env.sse_path,
+        streamable_http_path=(
+            args.streamable_http_path
+            if args.streamable_http_path is not None
+            else env.streamable_http_path
+        ),
+        allowed_hosts=allowed_hosts,
+        allowed_origins=allowed_origins,
+        disable_transport_security=disable_security,
+    )
+
+
+def _merge_allowed_hosts(hosts: tuple[str, ...], port: int) -> list[str]:
+    """合并用户配置与本地回环地址，供健康检查与容器内访问。"""
+    merged = list(hosts)
+    for item in (
+        f"127.0.0.1:{port}",
+        f"localhost:{port}",
+        "127.0.0.1:*",
+        "localhost:*",
+        "[::1]:*",
+    ):
+        if item not in merged:
+            merged.append(item)
+    return merged
+
+
+def _merge_allowed_origins(origins: tuple[str, ...], hosts: list[str]) -> list[str]:
+    merged = list(origins)
+    for host in hosts:
+        if host.startswith("http"):
+            candidate = host
+        else:
+            candidate = f"http://{host}"
+        if candidate not in merged:
+            merged.append(candidate)
+    for item in ("http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*"):
+        if item not in merged:
+            merged.append(item)
+    return merged
+
+
+def build_transport_security(config: RunConfig) -> TransportSecuritySettings:
+    """按监听地址与 allowed_hosts 构建传输安全策略。"""
+    if config.disable_transport_security:
+        return TransportSecuritySettings(enable_dns_rebinding_protection=False)
+
+    if config.allowed_hosts:
+        allowed_hosts = _merge_allowed_hosts(config.allowed_hosts, config.port)
+        origins = _merge_allowed_origins(config.allowed_origins, allowed_hosts)
+        return TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=allowed_hosts,
+            allowed_origins=origins,
+        )
+
+    if config.host in ("127.0.0.1", "localhost", "::1"):
+        return TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=[
+                f"{config.host}:*",
+                "127.0.0.1:*",
+                "localhost:*",
+                "[::1]:*",
+            ],
+            allowed_origins=[
+                f"http://{config.host}:*",
+                "http://127.0.0.1:*",
+                "http://localhost:*",
+                "http://[::1]:*",
+            ],
+        )
+
+    # 绑定 0.0.0.0 等对外地址时，必须显式配置 allowed_hosts
+    raise ValueError(
+        f"绑定到 {config.host}:{config.port} 时需配置允许的 Host 头，例如：\n"
+        f"  --allowed-host 192.168.0.18:{config.port}\n"
+        f"  --allowed-host 192.168.0.18:*\n"
+        f"或设置环境变量 MCP_ALLOWED_HOSTS=192.168.0.18:{config.port}\n"
+        f"局域网临时调试可加 --disable-transport-security（不推荐生产环境）"
+    )
+
+
+def apply_run_config(server: FastMCP, config: RunConfig) -> None:
+    """将网络相关设置写入 FastMCP 实例（启动前调用）。"""
+    server.settings.host = config.host
+    server.settings.port = config.port
+    server.settings.sse_path = config.sse_path
+    server.settings.streamable_http_path = config.streamable_http_path
+    if config.transport in ("streamable-http", "sse"):
+        server.settings.transport_security = build_transport_security(config)
+
+
+def run_server(server: FastMCP, config: RunConfig) -> None:
+    """按配置启动 MCP 服务。"""
+    apply_run_config(server, config)
+    transport: TransportName = config.transport  # type: ignore[assignment]
+    server.run(transport=transport)
+
+
+def main_entry(server: FastMCP, argv: list[str] | None = None) -> None:
+    try:
+        args = parse_cli_args(argv)
+        config = build_run_config(args)
+        run_server(server, config)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(2) from exc

src/config.py

@@ -0,0 +1,63 @@
+"""MCP server configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+DATA_DIR = PROJECT_ROOT / "data"
+
+TransportType = Literal["stdio", "streamable-http", "sse"]
+VALID_TRANSPORTS: frozenset[str] = frozenset({"stdio", "streamable-http", "sse"})
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="NEO4J_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    uri: str = "bolt://192.168.0.18:7687"
+    user: str = "neo4j"
+    password: str = "password"
+    database: str = "neo4j"
+
+    ontology_schema_path: Path = DATA_DIR / "ontology_schema.json"
+    query_patterns_path: Path = DATA_DIR / "query_patterns.yaml"
+
+    default_limit: int = 50
+    max_limit: int = 500
+    query_timeout_seconds: int = 30
+    max_traversal_depth: int = 4
+
+    stats_refresh_interval_seconds: int = 3600
+
+
+class McpSettings(BaseSettings):
+    """MCP 传输协议与 HTTP/SSE 监听配置（环境变量前缀 MCP_）。"""
+
+    model_config = SettingsConfigDict(
+        env_prefix="MCP_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    transport: TransportType = "stdio"
+    host: str = "127.0.0.1"
+    port: int = 8000
+    sse_path: str = "/sse"
+    streamable_http_path: str = "/mcp"
+    # 逗号分隔，如 192.168.0.18:7688 或 192.168.0.18:*
+    allowed_hosts: str = ""
+    allowed_origins: str = ""
+    disable_transport_security: bool = False
+
+
+settings = Settings()
+mcp_settings = McpSettings()