AI导哈

图分析服务器

一个基于NetworkX的图分析工具服务器，提供高效的图数据处理和分析功能，适用于需要图结构数据操作的场景。

  • by 0xCarsten
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 0xCarsten/Networkx-mcp

使用说明

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：节点对象列表，每个对象包含一个 id
  • links 或 edges：包含以下内容的边对象列表 source 和 target

可选标志：

  • directed （bool）：默认为 true 如果缺失
  • multigraph （bool）：默认为 true 如果缺失

示例：参见 data/example_graph.json 和 data/sample_graph_attr.json.

高效的图形加载（推荐）

为了尽量减少上下文和流量，请使用 图形缓存工作流程 而不是在每次工具调用时传递全图JSON：

  1. 加载一次：呼叫 load_graph_from_file 具有文件路径
  2. 多次引用：使用返回的 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": {"<value_as_string>": ["node1", "node2"], ...}}

find_best_matching_edge_attribute_vals

搜索 边缘属性值 通过子字符串匹配，返回按匹配值分组的匹配边。

  • 输入：
    • graph_data （dict，可选）：节点链接图 或
    • graph_uri （str，可选）：缓存的图引用（例如。， "graph://default")
    • attribute （str）：精确的边属性键
    • comparison （str）：要搜索的子字符串（不区分大小写）
  • 输出：
    • {"matching_edges": {"<value_as_string>": [(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 也是数字。

相关 MCP