# 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済みの環境にも依存しない。

## セットアップ

```bash
uv sync
```

## 使い方

```bash
# ワークスペースをスキャンしてキャッシュを構築
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への登録

このリポジトリのディレクトリ内で実行する:

```bash
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`を置くことでカスタマイズできる（このリポジトリ自体にはプロジェクト固有の知識を一切持たせない）。

```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`を再帰的に呼ぶ設計であり、パーサ自体は解決しない。