Sensa Graph MCP

MCP设置和使用指南

本指南解释了如何设置和运行资产图RAG MCP服务器、配置MCP工具以及在Cursor中使用它们。

目录

1. 先决条件
2. 项目设置
3. Neo4j配置
4. MCP服务器配置
5. 运行MCP服务器
6. 在游标中使用MCP工具
7. 可用的MCP工具
8. 故障排除

______________________________________________________________________

先决条件

在设置MCP服务器之前，请确保您已经：

• Python 3.8+ 安装
• Neo4j数据库 正在运行（建议使用5.x版本）
• 光标IDE 安装
• 虚拟环境 （推荐）

______________________________________________________________________

项目设置

1.克隆或导航到项目

cd /path/to/graph-sensa-rnd

2.创建虚拟环境

# Create virtual environment
python3 -m venv env

# Activate virtual environment
# On macOS/Linux:
source env/bin/activate
# On Windows:
# env\Scripts\activate

3.安装依赖项

pip install -r requirements.txt

该项目要求：

• neo4j>=5.14.0 -Neo4j Python驱动程序
• fastmcp>=2.0,=1.0.0 -环境变量管理

______________________________________________________________________

Neo4j配置

1.设置Neo4j数据库

确保您的Neo4j数据库正在运行。您可以使用：

• Neo4j桌面 （建议用于当地开发）
• Neo4j社区版 （独立）
• Neo4j光环 （云托管）

2.配置环境变量

创建一个 .env 项目根目录中的文件（或更新现有文件）：

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password_here
NEO4J_CONNECTION_TIMEOUT=15

重要提示： 替换 your_password_here 使用您实际的Neo4j密码。

3.验证Neo4j连接

您可以通过运行以下命令来测试连接：

python -c "from neo4j_config import get_driver; driver = get_driver(); print('Connected!' if driver else 'Failed'); driver.close()"

______________________________________________________________________

MCP服务器配置

MCP配置文件位置

Cursor的MCP配置文件位于：

~/.cursor/mcp.json

在macOS/Linux上，这扩展到：

/Users/your_username/.cursor/mcp.json

在Windows上：

C:\Users\your_username\AppData\Roaming\Cursor\User\globalStorage\mcp.json

mcp.json配置示例

这是一个完整的例子 mcp.json 文件：

{
    "mcpServers": {
        "asset-graph-rag": {
            "command": "/absolute/path/to/graph-sensa-rnd/env/bin/python",
            "args": [
                "/absolute/path/to/graph-sensa-rnd/main.py"
            ],
            "cwd": "/absolute/path/to/graph-sensa-rnd",
            "env": {
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USERNAME": "neo4j",
                "NEO4J_PASSWORD": "your_password_here"
            }
        }
    }
}

配置选项说明

• mcpServers：包含所有MCP服务器配置的对象
• asset-graph-rag：服务器标识符（可以是您喜欢的任何名称）
• command：虚拟环境中Python解释器的完整路径
• args：传递给Python解释器的参数数组（main.py文件）
• cwd：MCP服务器进程的工作目录
• env （可选）：传递给服务器进程的环境变量

重要提示

1. 使用绝对路径：始终在中使用绝对路径 mcp.json，而不是相对路径
2. 虚拟环境：点 command 到虚拟环境中的Python可执行文件(env/bin/python)
3. 环境变量：您可以：

- 设置它们 mcp.json 在...之下 env （如上所示） - 或者依靠 .env 项目目录中的文件（推荐）

1. 多个服务器：您可以将多个MCP服务器添加到 mcpServers 对象

多服务器示例

{
    "mcpServers": {
        "asset-graph-rag": {
            "command": "/Users/cefalo/Documents/graph-sensa-rnd/env/bin/python",
            "args": [
                "/Users/cefalo/Documents/graph-sensa-rnd/main.py"
            ],
            "cwd": "/Users/cefalo/Documents/graph-sensa-rnd"
        },
        "another-mcp-server": {
            "command": "/path/to/another/server/venv/bin/python",
            "args": [
                "/path/to/another/server/main.py"
            ],
            "cwd": "/path/to/another/server"
        }
    }
}

______________________________________________________________________

运行MCP服务器

方法1：直接执行（测试）

您可以直接运行MCP服务器进行测试：

# Activate virtual environment
source env/bin/activate

# Run the server
python main.py

服务器将启动并通过stdin/stdout等待MCP协议消息。

方法2：通过光标（制作）

配置后 mcp.json，Cursor将在需要时自动启动MCP服务器。服务器在后台运行，并通过MCP协议与Cursor通信。

方法3：独立测试

对于调试，您可以测试单个工具：

python -c "from tools.get_node_by_name import get_node_by_name; print(get_node_by_name('Biofilter 11'))"

______________________________________________________________________

在游标中使用MCP工具

1.验证MCP服务器是否正在运行

配置后 mcp.json:

1. 重新启动游标IDE
2. 打开MCP面板（通常可通过命令面板访问： Cmd+Shift+P → “MCP”）
3. 检查一下 asset-graph-rag 出现在可用服务器列表中

2.在聊天中使用工具

连接MCP服务器后，您可以使用自然语言查询：

查询示例：

• “Biofilter 11中有多少资产？”
• “列出图表中的所有类别”
• “与4号馆有什么联系？”
• “按类别统计资产”
• “有多少个地点？”

AI助手将自动使用适当的MCP工具来回答您的问题。

3.直接调用刀具

您还可以在提示中直接调用工具：

Use the get_node_by_name tool to find "Biofilter 11"

______________________________________________________________________

可用的MCP工具

资产图RAG MCP服务器提供以下工具：

节点发现工具

• get_node_by_name(name)：在所有节点类型（位置、系统、资产、类别）中按名称查找单个节点
• count_nodes_by_name(name)：计数名称完全匹配的节点
• count_by_label(label)：统计具有特定标签的所有节点（例如“资产”、“位置”）

分类工具

• list_categories(include_hierarchy=True)：列出所有类别节点及其BELONGS_TO层次结构
• count_assets_by_category(category_scope='both')：按位置和系统类别统计资产

连接工具

• describe_node_connections(name, include_attributes=False)：显示节点的所有传入和传出关系

容器内容工具

• container_contents_count_by_name(name, relationship_types, target_label=None, name_match='exact', parent_location_name=None, validity_filter=None)：按名称统计容器中的项目

- 使用 name_match='prefix' 部分比赛（例如，“大厅”比赛“大厅1”、“大厅2”）

• container_contents_list_by_name(name, relationship_types, target_label=None, name_match='exact', parent_location_name=None, validity_filter=None, limit=1000)：按名称列出容器中的项目

• container_contents_count(start_node_id, relationship_types, target_label=None, validity_filter=None)：使用node_id统计容器中的项目

• container_contents_list(start_node_id, relationship_types, target_label=None, validity_filter=None, limit=1000, include_attributes=None)：使用node_id列出容器中的项目

摘要工具

• count_assets_breakdown(container_type='Both', validity_filter=None)：每个地点和/或系统的资产明细

常见用例

统计某个位置的资产：

container_contents_count_by_name(
    name="Biofilter 11",
    relationship_types=["LOCATED_IN"],
    target_label="Asset"
)

列出所有大厅：

container_contents_list_by_name(
    name="Hall",
    relationship_types=["LOCATED_IN"],
    target_label="Location",
    name_match="prefix"
)

获取类别层次结构：

list_categories(include_hierarchy=True)

______________________________________________________________________

故障排除

MCP服务器未启动

1. 检查Python路径：验证 command 路径在 mcp.json 指向有效的Python可执行文件
2. 检查文件路径：确保所有路径 mcp.json 绝对正确
3. 检查权限：确保Python可执行文件和main.py可执行
4. 检查日志：在Cursor的MCP面板或控制台中查找错误消息

连接错误

1. Neo4j未运行：确保Neo4j正在运行且可访问
2. 错误的凭证：验证 .env 文件具有正确的Neo4J凭据
3. 网络问题：检查是否 NEO4J_URI 正确（默认值： bolt://localhost:7687)

导入错误

1. 缺少依赖关系：运行 pip install -r requirements.txt
2. 虚拟环境：确保您使用的是正确的虚拟环境
3. Python版本：验证是否安装了Python 3.8+

游标中没有可用的工具

1. 重新启动游标：修改后 mcp.json，完全重新启动Cursor
2. 检查MCP面板：验证服务器是否出现在MCP面板中
3. 检查服务器日志：查找MCP服务器日志中的错误

常见错误消息

“连接被拒绝”

• Neo4j未运行或URI不正确

“身份验证失败”

• 检查 NEO4J_USERNAME 和 NEO4J_PASSWORD 在 .env

“找不到模块”

• 安装依赖项： pip install -r requirements.txt

“找不到命令”

• 验证中的Python路径 mcp.json 是正确的

______________________________________________________________________

工作流示例

1. 设置环境：

   cd /path/to/graph-sensa-rnd
   python3 -m venv env
   source env/bin/activate
   pip install -r requirements.txt

1. 配置Neo4j：

   # Edit .env file
   NEO4J_URI=bolt://localhost:7687
   NEO4J_USERNAME=neo4j
   NEO4J_PASSWORD=your_password

1. 配置MCP：

   # Edit ~/.cursor/mcp.json
   # Add the asset-graph-rag server configuration

1. 重新启动光标：

- 完全关闭光标 - 重新打开光标 - 验证MCP服务器是否已连接

1. 测试设置：

- 问：“图中有多少资产？” - 或者：“列出所有类别”

______________________________________________________________________

其他资源

• FastMCP文档
• 模型上下文协议规范
• Neo4j Python驱动程序文档

______________________________________________________________________

支持

对于问题或疑问：

1. 检查上面的故障排除部分
2. 在Cursor中查看MCP服务器日志
3. 验证您的Neo4j数据库是否配置正确
4. 确保所有依赖项都已正确安装