Neo4j内存MCP
该项目实施了论文中的核心方法 *解决AI代理中的上下文窗口溢出问题*：工具不会将大型图形结果直接传递回模型上下文。相反，镜像工具将结果存储在运行时内存中，并返回短内存路径。稍后的工具在执行之前将这些路径解析回完整值。
它也遵循了官方的形状 neo4j/mcp 服务器通过暴露模式检查和Cypher执行工具，默认情况下启用只读模式。
包括什么
- 一个具有REST端点的FastAPI应用程序，用于每会话Neo4j连接设置、模式查找、读取查询、写入查询和内存检索。
- 安装在FastAPI应用程序内的FastMCP服务器
/mcp-server/mcp/. - 磁盘支持的运行时内存存储，用于存储超大或始终持久的工具输出。
- 会话范围的运行时内存，因此指针只能在原始会话中解析。
- 内存中的会话注册表，因此每个客户端会话都维护自己的Neo4j连接详细信息。
- 镜像Neo4j工具：
- configure-neo4j-session - get-neo4j-session-status - disconnect-neo4j-session - get-schema - read-cypher - write-cypher - describe-memory - retrieve-final-answer-from-memory - slice-memory-list
项目布局
src/neo4j_memory_mcp/
api/app.py FastAPI app and REST endpoints
mcp_server/server.py FastMCP tool definitions
config.py Environment-based settings
memory.py Pointer-based runtime memory store
neo4j_service.py Neo4j driver wrapper
runtime.py Shared application context
main.py Uvicorn entrypoint配置
复制 .env.example 到 .env 并设置：
NEO4J_DEFAULT_DATABASE=neo4j
NEO4J_DEFAULT_READ_ONLY=true
NEO4J_FETCH_SIZE=1000
NEO4J_QUERY_TIMEOUT_SECONDS=30服务器不再在其环境中存储单个Neo4j连接。客户端通过REST或MCP为每个会话提供连接详细信息，服务器在该会话的整个生命周期内将它们保存在内存中。
NEO4J_MEMORY_ALWAYS_STORE=true 通过返回工具输出的指针而不是原始有效载荷，使交互与论文保持一致。
当客户端连接时，服务器会发出不透明的会话令牌。对于之后的REST调用，请将其发送进来 X-Session-Token.
启动指南
cd "/Users/mac1/Documents/Codex Projects/Neo4j-memory-mcp"
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env编辑 .env 如果要覆盖数据库名称、只读模式、获取大小或查询超时的默认值：
NEO4J_DEFAULT_DATABASE=neo4j
NEO4J_DEFAULT_READ_ONLY=true
NEO4J_FETCH_SIZE=1000
NEO4J_QUERY_TIMEOUT_SECONDS=30然后启动服务器：
.venv/bin/uvicorn neo4j_memory_mcp.api.app:app --host 0.0.0.0 --port 8000如果先激活虚拟环境，则等效命令为：
source .venv/bin/activate
uvicorn neo4j_memory_mcp.api.app:app --host 0.0.0.0 --port 8000您还可以从虚拟环境中的模块入口点开始：
.venv/bin/python -m neo4j_memory_mcp.main启动后，检查：
- 健康：
http://localhost:8000/api/health - 会话连接：
POST http://localhost:8000/api/session/connect - 架构：
GET http://localhost:8000/api/schema - MCP传输：
http://localhost:8000/mcp-server/mcp/
端点
终点：
- REST API运行状况：
GET /api/health - REST会话连接：
POST /api/session/connect回报session_token - REST会话状态：
GET /api/session/status随着X-Session-Token - REST会话断开连接：
POST /api/session/disconnect随着X-Session-Token - REST架构：
GET /api/schema随着X-Session-Token - REST读取查询：
POST /api/query/read随着X-Session-Token - REST写入查询：
POST /api/query/write随着X-Session-Token - REST内存获取：
GET /api/memory/{memory_path}随着X-Session-Token - MCP传输：
/mcp-server/mcp/
论文如何映射到此代码
- 输入检查：
MemoryStore.resolve_if_pointer()检测工具参数是否是内存路径，并在底层函数运行之前解析它，但仅在当前会话命名空间内。 - 原始工具行为：
Neo4jService包含纯模式和Cypher操作。 - 会话绑定：
SessionManager生成不透明的会话令牌，并保留每个令牌的Neo4j连接设置和驱动程序，而无需将凭据写入磁盘。 - 后处理和内存路径返回：
AppContext.mirrored_call()存储结果并返回指针元数据，而不是大型原始有效载荷。 - 最终答案检索：
retrieve-final-answer-from-memory和GET /api/memory/{memory_path}当在创建结果的同一会话中明确请求时，返回存储的结果。
备注
- 只读密码保护是有意保守的，可以阻止常见的写入、管理、模式、APOC突变和
PROFILE声明。 - Neo4j密码仅在会话配置期间接受，并保存在进程内存中，而不是运行时内存存储或API响应中。
- 会话令牌是服务器生成的，而不是客户端选择的，这避免了意外冲突，并使令牌猜测变得更加困难。
get-schema用途apoc.meta.schema()，匹配安装APOC的官方Neo4j MCP服务器先决条件。- 对于非常大的列表结果，
slice-memory-list允许客户端在不重新运行查询的情况下拉回窗口。 - 运行时内存目录下的每个会话都有内存命名空间，因此一个会话无法解析另一个会话的指针。