AI导哈

知识图谱服务器

一个为AI代理提供知识图谱和向量存储访问的服务器，支持混合搜索和证据检索。

  • by engineering-with-ai
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 engineering-with-ai/software-python-mcp-server

使用说明

Python MCP服务器🧠

一种模型上下文协议（MCP）服务器，允许AI代理访问Graphiti 基于证据支持的知识图和pgvector文档存储 响应。

特性

  • 🔍 混合图搜索 --通过Graphiti实现语义+BM25+图遍历
  • 📚 矢量RAG --pg向量相似性搜索；查询字符串已嵌入 内部通过OpenAI（不需要调用者预先计算向量）
  • 🧾 证据检索，而非虚假验证 — verify_fact 回报 相关图形证据；LLM评委的召唤
  • ⚡ 快速失败 --客户端错误表现为MCP错误，而不是无声的空结果
  • ⚙️ 干净的配置拆分 — cfg.yml 对于config，env变量仅用于secrets

工具

工具 输入 返回
search_knowledge query: str 图形实体/关系
rag_search query: str 按相似性排序的文档块
verify_fact statement: str FactEvidence { statement, evidence }
combined_search query: str 图表结果+文档块

所有工具都采用字符串——嵌入是在服务器端生成的。

资源： knowledge://instructions, knowledge://examples. 提示： answer_with_verification.

快速开始

pip install python-mcp-server
# or
uvx python-mcp-server

配置

cfg.yml 保存所有非秘密配置。秘密只存在于环境中 变量——从不在 cfg.yml，从不在Postgres URL中。

cfg.yml

local:
  log_level: DEBUG
  neo4j:
    uri: bolt://localhost:7687
    user: neo4j
    database: neo4j
  postgres:
    host: localhost
    port: 5432
    database: knowledge
    user: postgres
    embeddings_table: energy_embeddings
    embedding_model: text-embedding-3-small

服务器根据以下内容选择顶级密钥 ENV env为（默认） local). A. beta 该部分也得到了支持。

秘密（环境）

export NEO4J_PASSWORD="..."
export POSTGRES_PASSWORD="..."
export OPENAI_API_KEY="..."
export ENV="local"

程序化使用

from python_mcp_server import create_server
from python_mcp_server.config import Config, Neo4jConfig, PostgresConfig, LogLevel

config = Config(
    log_level=LogLevel.INFO,
    neo4j=Neo4jConfig(uri="bolt://localhost:7687", user="neo4j", database="neo4j"),
    postgres=PostgresConfig(
        host="localhost", port=5432, database="knowledge", user="postgres",
        embeddings_table="energy_embeddings",
        embedding_model="text-embedding-3-small",
    ),
)
server = create_server(
    config=config,
    neo4j_password="...",
    postgres_password="...",
    openai_api_key="...",
)

用法

克劳德代码

export NEO4J_PASSWORD=... POSTGRES_PASSWORD=... OPENAI_API_KEY=...
claude mcp add domain-expert -- uvx python-mcp-server

克劳德桌面(claude_desktop_config.json)

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "uvx",
      "args": ["python-mcp-server"],
      "env": {
        "NEO4J_PASSWORD": "...",
        "POSTGRES_PASSWORD": "...",
        "OPENAI_API_KEY": "..."
      }
    }
  }
}

Pydantic AI

from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

mcp = MCPServerStdio("uvx", "python-mcp-server")
agent = Agent(toolsets=[mcp])
result = await agent.run("What connects Tesla and battery technology?")

数据库模式

预期的pgvector表 rag_search:

CREATE TABLE energy_embeddings (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT NOT NULL,
    book TEXT,
    section_level TEXT,
    analysis_relevance TEXT,
    embedding vector(1536),  -- text-embedding-3-small
    content_tsv tsvector
        GENERATED ALWAYS AS (to_tsvector('english', content)) STORED
);

CREATE INDEX ON energy_embeddings USING ivfflat (embedding vector_cosine_ops);
CREATE INDEX idx_content_tsv ON energy_embeddings USING gin(content_tsv);

嵌入尺寸必须匹配 embedding_model 在 cfg.yml.

rag_search 根据此表发布两个排名——余弦超过 embedding BM25以上 content_tsv --并通过互易秩融合将它们融合在一起 （k=60）。精确的术语匹配（协议字段名、枚举值、要求 ID）通过BM25腿，纯余弦会错过。

发展

git clone <repo> && cd python-mcp-server
uv sync --dev
cp template-secrets.env .env  # fill in secrets

uv run poe checks   # deptry, black, ruff, mypy, bandit, pip-audit
uv run poe cover    # tests with coverage
uv run python-mcp-server

建筑

src/python_mcp_server/
├── clients/
│   ├── embedder.py         # OpenAI embeddings (injected)
│   ├── graphiti_client.py  # Neo4j via Graphiti
│   └── rag_client.py       # pgvector similarity search
├── config.py               # cfg.yml loader
├── models.py               # Pydantic response models
├── server.py               # FastMCP tools, resources, prompt
└── __main__.py             # CLI entry point

设计原则

  1. 输入，输出证据。 呼叫者传递自然语言；服务器 处理嵌入并返回类型化的Pydantic结果。
  2. 没有虚假验证。 verify_fact 归还证据；呼叫者LLM 决定蕴涵。服务器从不发明 verified: bool.
  3. 失败很快。 数据库错误会传播到MCP客户端，因此Claude可以看到 “Neo4j无法访问”而不是“没有结果”
  4. 配置与秘密是两个不同的问题。 cfg.yml 已办理入住手续； 密码和API密钥从来都不是。

相关 MCP