NetworkX MCP服务器
此存储库提供了一个MCP（模型上下文协议）服务器，该服务器公开了一小部分 图形分析工具 建在上面 NetworkX服务器是通过以下方式实现的 FastMCP 并通过以下方式托管 快速API.
这些工具的设计便于LLM正确调用：每个工具都有一个图 NetworkX节点链接JSON 格式化并返回一个小的JSON对象。
项目结构
networkx-mcp/
├── main.py # Server entry point (FastAPI + FastMCP)
├── src/
│ ├── cache.py # Graph caching infrastructure
│ ├── tools.py # MCP tool definitions
│ ├── resources.py # MCP resource definitions
│ └── base/
│ ├── base.py # Graph construction utilities
│ └── graph_analytics.py # Node/edge filtering logic
├── data/ # Example graph JSON files
└── pyproject.toml # Project dependencies关键原则：
main.py仅初始化并启动服务器- 工具定义见
src/tools.py并通过注册register_tools() - 资源定义见
src/resources.py并通过注册register_resources() - 图缓存逻辑被隔离在
src/cache.py
图形输入格式（重要）
所有接受的工具 graph_data 预期 NetworkX节点链接JSON （Python dict)，由 networkx.node_link_data(G).
最低要求结构：
nodes：节点对象列表，每个对象包含一个idlinks或edges：包含以下内容的边对象列表source和target
可选标志：
directed（bool）：默认为true如果缺失multigraph（bool）：默认为true如果缺失
示例：参见 data/example_graph.json 和 data/sample_graph_attr.json.
高效的图形加载（推荐）
为了尽量减少上下文和流量，请使用 图形缓存工作流程 而不是在每次工具调用时传递全图JSON：
- 加载一次：呼叫
load_graph_from_file具有文件路径 - 多次引用：使用返回的
graph://后续工具调用中的URI
工作流程示例:
# Step 1: Load the graph (transmits file path only, ~50 bytes)
result = load_graph_from_file(
path="/path/to/my_graph.json",
alias="mygraph"
)
# Returns: {"status": "loaded", "uri": "graph://mygraph", "node_count": 100, ...}
# Step 2: Use the URI in all subsequent calls (transmits ~20 bytes)
path = shortest_path(
graph_uri="graph://mygraph", # ← Reference cached graph
source="A",
target="B"
)
# Step 3: More calls using same URI
nodes = find_nodes_by_attribute(
graph_uri="graph://mygraph",
attribute="type",
operator="==",
value="important"
)交通比较:
- ❌ 无缓存：每次调用都会传输全图JSON（可以是兆字节）
- ✅ 使用缓存：加载一次（~文件大小），然后每次调用只传输约20个字节的URI
备注：所有工具支持 两者 graph_data （直接JSON）和 graph_uri （缓存引用）。为您的用例选择最佳方法。
工具
load_graph_from_file
从JSON文件加载图形并在服务器端缓存，以实现高效重用。
- 输入：
- path （str）：NetworkX节点链接JSON文件的绝对或相对文件路径 - alias （str，可选）：缓存键（默认值： "default")
- 输出：
- 成功： {"status": "loaded", "alias": "...", "uri": "graph://...", "node_count": N, "edge_count": M, "directed": bool, "multigraph": bool} - 失败： {"error": "..."} （例如，找不到文件、JSON无效、图形模式无效）
- 副作用： 将图形存储在服务器内存中.使用返回的
uri在后续的工具调用中，避免重新传输图形数据。
health_check
生命探测。
- 输入：无
- 输出：
{"status": "ok"} - 副作用：无
shortest_path
计算a 未加权的 两个节点之间的最短路径。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - source （str）：节点id（必须存在） - target （str）：节点id（必须存在）
- 输出：
- 成功： {"path": ["nodeA", "nodeB", ...]} - 失败： {"error": "..."} （例如，没有路径、找不到节点、架构无效）
- 副作用：无
find_nodes_by_attribute
使用比较运算符按节点属性过滤节点。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - attribute （str）：节点属性键 - value （any|null）：要比较的值；如果 null，该工具仅检查属性是否存在 - operator （str）：其中之一 ==, !=, `, >=`
- 行为：
- 如果 value 是 null：返回节点，其中 attrs[attribute] 存在且不为空。 - Else：返回以下节点 attrs[attribute] operator value 这是真的。
- 输出：
- 成功： {"matching_nodes": ["A", "B", ...]} - 失败： {"error": "..."} （例如，不支持的运算符、不可比较的类型）
find_edges_by_attribute
使用比较运算符按边属性过滤边。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - attribute （str）：边属性键 - value （任意|空） - operator （str）：其中之一 ==, !=, `, >=`
- 输出：
- 成功： {"matching_edges": [...]} - 对于多图：元组列表 (u, v, key) - 对于非MultiGraphs：元组列表 (u, v) - 失败： {"error": "..."}
find_best_matching_node_attribute
发现 节点属性名称 部分匹配搜索字符串。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - attribute （str）：搜索字符串
- 行为：不区分大小写的子字符串与节点属性键匹配。
- 输出：
{"matching_attributes": ["holdup_max", "holdup_min", ...]}
find_best_matching_edge_attribute
发现 边属性名称 部分匹配搜索字符串。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - attribute （str）：搜索字符串
- 行为：不区分大小写的子字符串与边缘属性键匹配。
- 输出：
{"matching_attributes": ["capacity", "transport_time", ...]}
find_best_matching_node_attribute_vals
搜索 节点属性值 通过子字符串匹配，返回按匹配值分组的匹配节点。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - attribute （str）：精确的节点属性键 - comparison （str）：要搜索的子字符串（不区分大小写）
- 输出：
- {"matching_nodes": {"": ["node1", "node2"], ...}}
find_best_matching_edge_attribute_vals
搜索 边缘属性值 通过子字符串匹配，返回按匹配值分组的匹配边。
- 输入：
- graph_data （dict，可选）：节点链接图 或 - graph_uri （str，可选）：缓存的图引用（例如。， "graph://default") - attribute （str）：精确的边属性键 - comparison （str）：要搜索的子字符串（不区分大小写）
- 输出：
- {"matching_edges": {"": [(u, v) or (u, v, key), ...], ...}}
运行服务器
此repo使用 justfile.
- 启动FastAPI（为MCP提供服务）
/api/mcp):
- just fastapi_run
- 通过FastMCP CLI（HTTP传输）启动：
- just mcp_run
使用的默认URL client.py:
http://localhost:8000/api/mcp
LLM工具调用者注意事项
- 总是通过a 单 在调用工具时使用params对象（例如。，
{"graph_uri": "graph://default", "source": "A", "target": "B"}). - 节点ID通常是字符串（请参阅示例JSON文件）。
- 为了提高效率：使用
load_graph_from_file一次缓存图形，然后通过引用它graph_uri在所有后续通话中。这将流量从兆字节减少到字节。 - 灵活性：接受所有工具 要么
graph_data（直接JSON） 或graph_uri（缓存引用），但不能同时使用。 - 用于数字比较(
=, ...），确保图中的属性值是数字，并且提供value也是数字。