CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7mcp-attrは、Model Context Protocol (MCP) サーバーを宣言的に構築するためのRustライブラリです。属性マクロを使用してMCPサーバーを簡単に作成できるように設計されています。
8 
9### Architecture
10 
11このプロジェクトは3つのワークスペースメンバーで構成されています：
12 
13- **mcp-attr**: メインライブラリ。MCPサーバーとクライアントの実装
14- **mcp-attr-macros**: プロシージャルマクロの実装 (`#[mcp_server]`, `#[tool]`, `#[resource]`, `#[prompt]`)
15- **codegen**: スキーマ生成とコード生成用のユーティリティ
16 
17### Key Components
18 
19- `#[mcp_server]` 属性によるMCPサーバーの宣言的記述
20- `#[tool]`, `#[resource]`, `#[prompt]` 属性による機能の実装
21- `#[complete_fn]` 属性による補完機能の実装（追加引数対応）
22- MCPクライアント（テスト用）
23- 型システムを活用したスキーマ生成
24 
25### Completion Function Enhancement (`#[complete_fn]`)
26 
27`#[complete_fn]` 属性に追加引数機能を実装しました：
28 
29#### 基本的な使用方法
30```rust
31#[complete_fn]
32async fn complete_with_args(&self, value: &str, category: &str, count: Option<u32>) -> Result<Vec<String>> {
33    // 実装
34}
35```
36 
37#### 対応している引数型
38- `&str`: 必須文字列引数
39- `Option<&str>`: オプショナル文字列引数
40- `T: FromStr`: 必須の型変換可能な引数
41- `Option<T: FromStr>`: オプショナルの型変換可能な引数
42 
43#### 引数の動作
44- 引数は `CompleteRequestParams::context::arguments` (BTreeMap) から取得
45- オプショナル引数がない場合は `None` を返す
46- 必須引数がない場合は空の補完結果を返す
47- 型変換に失敗した場合はエラーを返す
48- 型互換性チェックはコンパイル時に行われる
49 
50#### テスト
51- 統合テスト: `tests/completion_*.rs` のマトリックス構造テスト
52- コンパイル失敗テスト: `tests/compile_fail/completion_*.rs`
53 
54## Development Commands
55 
56### Build and Test
57```bash
58# 全パッケージのビルド
59cargo build
60 
61# 特定パッケージのビルド
62cargo build -p mcp-attr
63cargo build -p mcp-attr-macros
64cargo build -p mcp-attr-codegen
65 
66# テスト実行
67cargo test
68 
69# 特定パッケージのテスト
70cargo test -p mcp-attr
71 
72# ドキュメントテスト
73cargo test --doc
74 
75# コンパイル失敗テスト（trybuild）
76cargo test --test compile_fail -- --ignored
77```
78 
79### Code Quality
80```bash
81# 型チェック
82cargo check
83 
84# テストのコンパイルチェック（実行なし）
85cargo test --no-run
86 
87# Clippy（リンター）
88cargo clippy
89 
90# 自動修正
91cargo clippy --fix --allow-dirty
92 
93# ドキュメント生成
94cargo doc
95 
96# フォーマット
97cargo fmt
98```
99 
100### Examples
101```bash
102# サンプル実行
103cargo run --example char_count
104cargo run --example tool_info
105```
106 
107## Testing Strategy
108 
109### Test Organization
110- `tests/` ディレクトリ: 統合テスト
111- `tests/mcp_server_*.rs`: `#[mcp_server]` 属性のテスト（型ごとに1ファイル）
112- `tests/compile_fail/`: コンパイル失敗テスト（trybuild使用）
113- モジュール内 `tests` モジュール: 非公開項目のテスト
114 
115### Test Guidelines
116- 新機能実装時は必ずテストを作成
117- 複数テスト追加時は1つずつ追加して確認
118- テストデータは英語を使用（非ASCII文字テスト時を除く）
119 
120### Debugging `#[mcp_server]` Macro
121マクロのデバッグ時：
1221. `#[mcp_server]` を `#[mcp_server(dump)]` に変更
1232. テスト実行でマクロ展開後コードを確認
1243. 展開後コードを直接編集してデバッグ
1254. 修正内容をマクロ実装に反映
126 
127## Completion Tests Structure
128 
129### Test File Organization
130 
131Completion functionality tests are organized in a matrix structure based on:
132- **Usage context**: prompt vs resource
133- **Definition location**: global (global functions) vs impl (methods in #[mcp_server] impl)
134 
135#### Success Case Tests
136```
137tests/
138├── completion_prompt_global.rs    # Prompt + Global completion functions
139├── completion_prompt_impl.rs      # Prompt + Impl completion methods  
140├── completion_resource_global.rs  # Resource + Global completion functions
141├── completion_resource_impl.rs    # Resource + Impl completion methods
142└── completion_edge_cases.rs      # Special cases not covered by the matrix
143```
144 
145#### Compile Failure Tests
146Located in `tests/compile_fail/` with naming pattern: `completion_[category]_[error].rs`
147 
148### Adding New Completion Tests
149 
150#### For Common Functionality
151When adding a new test for functionality that applies to all completion contexts:
1521. **MUST add the test to all 4 matrix files** (completion_prompt_global, completion_prompt_impl, completion_resource_global, completion_resource_impl)
1532. Use consistent test naming across all files
1543. Only exclude from specific files if functionality is genuinely incompatible
1554. Document any exclusions with clear comments
156 
157#### For Special Cases
158Use `tests/completion_edge_cases.rs` for cross-context integration tests, manual overrides, and cases that don't fit the matrix structure.
159 
160## Code Style
161 
162### Rust Conventions
163- Rustの慣例とベストプラクティスに従う
164- 関数名・型名は一貫性と対称性を重視
165- 理解困難なコードのみにコメント付与
166- バグ以外でErrが返されない場合はResultを使わずパニック
167 
168### Error Handling
169- `mcp_attr::Result` と `mcp_attr::Error` を使用
170- `bail!` (プライベート) と `bail_public!` (パブリック) マクロを活用
171- 依存関係のエラーはプライベート情報として扱う
172 
173### Documentation
174- 公開項目には適切なdocコメントを付与
175- 最初の行は簡潔な1行説明
176- 関連する型・関数は `[]` でリンク
177- `cargo test --doc` と `cargo doc` で検証
178 
179## Dependencies
180 
181### Main Dependencies
182- `serde`: JSON シリアライゼーション
183- `tokio`: 非同期ランタイム
184- `schemars`: JSON Schema生成
185- `jsoncall`: JSON-RPC実装
186- `uri-template-ex`: URI Template処理
187 
188### Development Dependencies
189- `trybuild`: コンパイル失敗テスト
190- `pretty_assertions`: テストアサーション
191 
192## Documentation Generation
193 
194### tests_readme.rs (Auto-generated File)
195 
196**IMPORTANT**: `mcp-attr/src/tests_readme.rs` is an auto-generated file and should NOT be edited directly.
197 
198- **Source**: Generated from `README.ja.md` (Japanese README)
199- **Generation Command**: `rustdoc-include --root /path/to/project`
200- **When to Regenerate**: 
201  - After modifying README.md or README.ja.md
202  - When doctest examples need updating
203  - When completion function examples change
204 
205### Workflow for Updating Documentation Examples
206 
2071. Edit the source README file (`README.md` for English, `README.ja.md` for Japanese)
2082. Run `rustdoc-include --root .` to regenerate tests_readme.rs
2093. Run `cargo test --doc` to verify all doctests pass
2104. Any direct edits to tests_readme.rs will be overwritten on next generation
211 
212### rustdoc-include Usage
213 
214```bash
215# Regenerate tests_readme.rs from README files
216rustdoc-include --root .
217```
218 
219This command processes files with `#![include_doc("filename", start/end)]` markers and generates documentation tests.
220 
221## Important Notes
222 
223- 依存関係のバージョンダウンは禁止
224- カレントディレクトリ変更は避け、コマンド引数で対応
225- エラー修正3回失敗時はスキップして他の箇所を修正
226- 依存関係の追加・変更は禁止とし、必要な場合はユーザーによる手動編集を促すこと
227- **tests_readme.rsは自動生成ファイルのため直接編集しない** - README.mdを編集してrustdoc-includeで再生成する