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
