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