使用说明

MCP设置和使用指南

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

先决条件

在设置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,<3 -MCP服务器的FastMCP框架
python-dotenv>=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 （可选）：传递给服务器进程的环境变量

重要提示

使用绝对路径：始终在中使用绝对路径 mcp.json，而不是相对路径
虚拟环境：点 command 到虚拟环境中的Python可执行文件(env/bin/python)
环境变量：您可以：
- 设置它们 mcp.json 在...之下 env （如上所示）
- 或者依靠 .env 项目目录中的文件（推荐）
多个服务器：您可以将多个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:

重新启动游标IDE
打开MCP面板（通常可通过命令面板访问： Cmd+Shift+P → “MCP”）
检查一下 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服务器未启动

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

连接错误

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

导入错误

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

游标中没有可用的工具

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

常见错误消息

“连接被拒绝”

Neo4j未运行或URI不正确

“身份验证失败”

检查 NEO4J_USERNAME 和 NEO4J_PASSWORD 在 .env

“找不到模块”

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

“找不到命令”

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

工作流示例

设置环境：

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

配置Neo4j：

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

配置MCP：

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

重新启动光标：
- 完全关闭光标
- 重新打开光标
- 验证MCP服务器是否已连接
测试设置：
- 问：“图中有多少资产？”
- 或者：“列出所有类别”

其他资源

支持

对于问题或疑问：

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