rosgraph-mcp
Provides tools for exploring ROS2 workspace graph knowledge, including package dependencies, message/service/action definitions, and topic pub/sub relationships, all through static file analysis without requiring a running ROS2 environment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rosgraph-mcp What are the dependencies of the planning package?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rosgraph-mcp
ROS2ワークスペースの「グラフ的知識」(パッケージ依存、メッセージ/サービス/アクション定義とその使用箇所、トピックのpub/sub関係)を、素のLSPやSerenaのようなシンボル検索ツールでは扱えない粒度で提供するMCPサーバー + ローカルWebダッシュボード。
なぜ作ったか
Claude Codeにはclangd-lspプラグインのようなネイティブの宣言的LSP統合があり、シンボル定義/参照検索は既にそちらでカバーされている(~/.claude/plugins/参照)。このツールはそれを再実装せず、LSPが理解できないROS2固有のクロスファイル・クロスパッケージ概念(package.xmlの依存グラフ、.msg/.srv/.actionの定義とその使用箇所、トピックのpub/sub接続)だけに集中する。
外部ネットワーク通信はゼロ。すべて静的ファイル解析で完結し、ros2/colcon CLIやビルド・source済みの環境にも依存しない。
Related MCP server: ROS 2 Workspace Inspector MCP
セットアップ
uv sync使い方
# ワークスペースをスキャンしてキャッシュを構築
uv run rosgraph-mcp scan --workspace /path/to/ros2_ws
# MCPサーバーとして起動 (stdio)
uv run rosgraph-mcp serve
# ダッシュボードを起動 (http://127.0.0.1:8765)
uv run rosgraph-mcp dashboard --workspace /path/to/ros2_wsClaude Codeへの登録
このリポジトリのディレクトリ内で実行する:
claude mcp add --scope user rosgraph -- uv run --project "$(pwd)" rosgraph-mcp serve特定のワークスペースを既定にしたい場合は、--env ROSGRAPH_MCP_WORKSPACE=/path/to/ros2_wsを追加するか、各ツール呼び出し時にworkspace_rootを指定する。
提供するMCPツール(Phase 1時点)
ツール | 説明 |
| ワークスペース内のパッケージ一覧(グループ/サブグループ/名前でフィルタ可) |
| このワークスペースに実際に存在するグループ/サブグループの一覧 |
| 指定パッケージの依存関係( |
| キャッシュを明示的に再構築 |
今後のフェーズで.msg/.srv定義検索、pub/subグラフツールを追加予定(詳細は設計書参照)。
グループ/サブグループの分類(どのROS2ワークスペースでも動く汎用ツール)
デフォルトでは特定プロジェクトの知識を一切前提にしない、汎用的な分類ルールのみを使う:
グループ =
src/<group>/...の最初のパスセグメントそのままサブグループ = その直下のディレクトリ名
これだけで大抵のROS2ワークスペースはそれなりに意味のある分類になるが、より細かい分類をしたいプロジェクトは、ワークスペースのルートに.rosgraph-mcp.tomlを置くことでカスタマイズできる(このリポジトリ自体にはプロジェクト固有の知識を一切持たせない)。
# <workspace_root>/.rosgraph-mcp.toml
[groups.core]
# src/launch/, src/launch_ros/, src/rclcpp/ を "core" という1つのグループにまとめる
aliases = ["launch", "launch_ros", "rclcpp"]
[groups.autoware]
# src/autoware/universe/planning/... のように、universe/core の直下にさらに
# カテゴリディレクトリがある場合、サブグループを "universe-planning" のように
# 1階層深く分類する
tier_dirs = ["universe", "core"]設定ファイルが無ければ完全に汎用的な既定ルールのみが使われる。list_groupsで実際にどう分類されたかをいつでも確認できる。
既知の制約
pub/sub検出(Phase 3以降)は正規表現ベースのヒューリスティックであり、完全なAST解析ではない。変数経由のトピック名、launchファイルでのリマップは検出できない場合がある。
.msg/.srv/.actionのネスト型解決は、呼び出し側がfind_message_definitionを再帰的に呼ぶ設計であり、パーサ自体は解決しない。
Available Tools
4 toolsget_package_dependenciesA
Get a package's dependencies (from package.xml) and, conversely, which
packages depend on it. depend_types filters to a subset of
depend/build_depend/exec_depend/test_depend/buildtool_depend (default: all).
transitive=True walks the full dependency closure instead of one hop.
Inputs: package_name (required), transitive, depend_types, workspace_root.
list_groupsA
List every group and, within each, the subgroups actually present in
this workspace. By default these are derived generically from the src/
directory layout (group = first path segment, subgroup = the next one);
a workspace can opt into richer classification via an optional
.rosgraph-mcp.toml at its root (see the README). Call this before using
subgroup filters on list_packages/the dashboard to see valid values.
Inputs: workspace_root.
list_packagesA
List ROS2 packages in the workspace, optionally filtered by group (the
top-level src// directory a package lives under — this varies by
workspace, e.g. "vendor"/"description" for one repo, something else
entirely for another), a finer-grained subgroup within it, or a
case-insensitive substring of the package name. Call list_groups first
to see the actual group/subgroup values present in this workspace.
Inputs: group, subgroup, name_filter, workspace_root.
rescan_workspaceA
Rebuild the package index cache for a workspace by re-scanning all
package.xml files under it. Call this after pulling new source or after
vcs import changes the set of packages — the index is not auto-refreshed
on every tool call for performance reasons.
Inputs: workspace_root.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: list_groups exposes the grouping hierarchy, list_packages lists packages with filters, get_package_dependencies analyzes dependency relationships, and rescan_workspace refreshes the cache. There is no overlap or ambiguity among them.
All tool names follow a consistent verb_noun pattern in snake_case: list_groups, list_packages, get_package_dependencies, rescan_workspace. The naming is predictable and uniform.
With only 4 tools, the set is tightly scoped for a ROS2 workspace graph server. Each tool addresses a distinct need, and the count is appropriate for the server's purpose without feeling thin or bloated.
The tool surface covers the core workflows: discovering groups, listing packages, querying dependencies (forward and reverse), and refreshing the index after changes. There are no obvious dead ends or missing operations for the stated domain of package graph exploration.
Maintenance
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceProvides a local code knowledge graph for Java projects, enabling querying of classes, methods, fields, calls, inheritance, and imports via MCP tools like query, context, impact, and cypher.1-
- AlicenseAqualityDmaintenanceProvides static analysis of ROS 2 workspaces, enabling inspection of packages, dependencies, interfaces, launch files, and robot descriptions without running ROS 2.72Apache 2.0
- AlicenseNot gradedqualityAmaintenanceProvides a traversable knowledge graph of the NVIDIA NemoClaw stack, enabling deterministic queries over its architecture, dependencies, and policies via MCP.2MIT
- AlicenseNot gradedqualityDmaintenanceExposes code graphs across multi-program repositories via MCP, enabling humans and agents to query the fleet with evidence.MIT