Skip to main content
Glama

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_ws

Claude 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時点)

ツール

説明

list_packages

ワークスペース内のパッケージ一覧(グループ/サブグループ/名前でフィルタ可)

list_groups

このワークスペースに実際に存在するグループ/サブグループの一覧

get_package_dependencies

指定パッケージの依存関係(package.xml由来、1ホップ)

rescan_workspace

キャッシュを明示的に再構築

今後のフェーズで.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 tools
get_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

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers