| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 2 | 31 | 3% |
| Commands | 2 | 0 | 14 | 13% |
| Section tags | 2 | 0 | 7 | 22% |
What each file covers
Sections
1 shared · 2 only in A · 31 only in B- − doc commentのテスト
- − Default の実装方法
- + CLAUDE.md
- + Project Overview
- + Architecture
- + Key Components
- + Completion Function Enhancement (`#[complete_fn]`)
- + Development Commands
- + Build and Test
- + コンパイル失敗テスト（trybuild）
- + Code Quality
- + Clippy（リンター）
- + Examples
- + Testing Strategy
- + Test Organization
- + Test Guidelines
- + Debugging `#[mcp_server]` Macro
- + Completion Tests Structure
- + Test File Organization
- + Adding New Completion Tests
- + Code Style
- + Rust Conventions
- + Error Handling
- + Documentation
- + Dependencies
- + Main Dependencies
- + Development Dependencies
- + Documentation Generation
- + tests_readme.rs (Auto-generated File)
- + Workflow for Updating Documentation Examples
- + rustdoc-include Usage
- + Regenerate tests_readme.rs from README files
- + Important Notes
- コマンドの実行方法
Commands
2 shared · 0 only in A · 14 only in B- + cargo build
- + cargo build -p mcp-attr
- + cargo build -p mcp-attr-macros
- + cargo build -p mcp-attr-codegen
- + cargo test
- + cargo test -p mcp-attr
- + cargo test --test compile_fail -- --ignored
- + cargo check
- + cargo test --no-run
- + cargo clippy
- + cargo clippy --fix --allow-dirty
- + cargo fmt
- + cargo run --example char_count
- + cargo run --example tool_info
- cargo test --doc
- cargo doc
Section tags
2 shared · 0 only in A · 7 only in B- + build
- + lint-format
- + code-style
- + architecture
- + testing-strategy
- + dependencies
- + agent-behaviour
- test
- docs
Line diff
frozenlib/mcp-attr · .cursor/rules/rust.mdc
@@ −1 @@
1---
2description: Rustのコードの書き方
3globs: *.rs
4alwaysApply: true
5---
6
7# 基本方針
8
9- Rustの慣例やベストプラクティスに沿ったコードを書きます
10- 新しい機能を実装したり既存の機能のコードを修正した場合は、その機能のテストがあるかを確認し、無ければテストを作成します
11- 関数名や型名は一貫性、対称性を重視します。
12- doc commentでない通常のコメントは、理解が困難なコードにのみ付け、理解が容易なコードにはコメントを付けません
13- エラー処理は、バグ以外でErrが返されることがないことが分かっている場合はResultを使用せず、パニックさせます
14- コンパイラの警告が発生した場合は、なにが悪くて警告が発生しているのかを考え、実際にコードが悪いと判断された場合は修正してください
15
16# コンパイルエラーが発生した場合の対処
17
18- 型エラーが発生したときには設計に問題がないか確認し、設計の問題に起因して型エラーが発生している場合は再設計を行います
19- 依存関係のバージョンを下げてはなりません
20- エラーの修正に失敗した場合は 下記の方法で情報を確認し、その情報を元にエラーの解決方法を考えてください
21 - `read_crate_readme` ツールを使用してエラーに関連する crate の readme を確認する
22 - `search_crate_source` ツールを使用してエラーに関連する型や関数を検索し、検索結果のファイルを `read_crate_file` ツールで取得して確認する
23- 同一個所のエラーの修正に3回連続で失敗した場合はコードを元に戻し、その修正はスキップし、別の場所を修正してください
24- スキップしたエラーのみが残っている場合は、スキップしたエラーの一覧をユーザーに提示し、ユーザーによる修正を待機してください
25
26# テストの書き方
27
28- `tests` フォルダ内のテストでは`mod tests`は不要です。
29- publicでない項目のテストを行う場合は、`tests/` ディレクトリにテストを配置するのではなく、実装対象のモジュール内の `tests` モジュールに書きます。
30- `tests` モジュールは別のファイルにします。
31- 1つのテストでのみ使用する型や関数がある場合は、テスト関数内で定義します
32- 複数のテストを追加する際は、一つずつテストを追加し、追加したテストを実行してパスすることを確認してから次のテストを追加してください。
33- テストを通す為だけに、テストケースの入力のみで処理を変えてはなりません
34- テストデータを作成する際は英語のデータを作成して下さい。ただし、非ASCII文字のテストを行う場合は英語以外のデータを作成しても良いです。
35
36# doc commentの書き方
37
38- `mod xxx;` のように独立したファイルで定義されたモジュールの場合は、そのモジュールの子項目が定義されたファイルを開き、そのファイルの先頭に `//!` 形式のコメントを書きます。それ以外は項目の前に `///` 形式のコメントを書きます。
39- 項目に属性がついている場合は、属性の後ではなく、前にコメントを書きます。
40- ドキュメントコメントを書く際は、ソースコードや他のドキュメントコメントをよく確認し、正しい内容を書いてください。
41- 最初の一行にはその項目を端的に表現する非常に簡潔な1行の説明を書きます
42 - 最初の一行は他の項目と同じにならないようにしてください。同じ説明文になってしまう場合は、何が違うのかを考え、それぞれに異なる説明を設定してください。
43- 最初の一行を含め、全てのドキュメントコメントでは一貫性のある表現を使用してください
44- 最初の1行とシグネチャからその項目の用途が充分に理解できる場合は、1行のコメントのみにしてください
45- そうでない場合は、2行目を空行とし、3行目以降に詳細な説明と使用例を書いてください。
46- 他の関数や型と関連性がある場合は、説明文の中で関連する関数や型の名前を [``] で囲って使用し、リンクを付けます。
47 - 例えば `XXX` 型を作成する `XXXBulder` があった場合、`XXX` 型のドキュメントには `XXXBuilder` のリンクを、`XXXBuilder` のドキュメントには `XXX` のリンクを含めます。
48 - 例えば、`XXX` 型が `fn xxx() -> XXX` の戻り値を実装する事のみが目的の場合は `XXX` 型の説明に `fn xxx` のリンクを含めます。この場合、 `fn xxx` のリンクに `XXX` を含める必要はありません。（シグネチャから自動的にリンクされるため）
49
50## 全てのdoc commentの検証
51
52全てのドキュメントコメントを書き終わったら、下記のテストを行います。
53書くべきドキュメントコメントが他にも残っている場合は、テストはまだ行わず、ドキュメントの作成を優先します。
54
55- `cargo test --doc` を実行し、ドキュメントコメント中に含まれるコードに間違いがないか確認します
56 - 間違いがなくなるまで修正と `cargo test --doc` を繰り返します
57- `cargo doc` を実行し、ドキュメント生成時に警告が発生しないかを確認します
58 - 警告が無くなるまで修正と `cargo doc` を繰り返します
59
60## doc commentのテスト
61
62- `// #![include_doc("ファイル名", start)]`, `// #![include_doc("ファイル名", end)]`で囲まれた部分は、コマンド `rustdoc-include` を実行することで指定したファイルからコピーされます。指定されたファイルの内容を変更した後、テストを行う際は`rustdoc-include --root <ROOT_DIR>`を実行してください。このコマンドが成功した場合、何もメッセージは出力されず、終了コードが0となります。
63
64## 日本語のコメントの表現
65
66日本語でコメントを書く場合は下記の書き方に従ってください
67
68- 最初の一行では、その項目が名詞で表現できる場合は、名詞で文を終える。例えば `～の型です` ではなく `～の型` のように表現する。
69
70# Default の実装方法
71
72Defaultを実装する場合は、次の順番で実装を試みてください
73
741. 標準の `#[derive(Defualt)]` を使用
752. `derive-ex` crateの `#[derive(Ex)]` `#[derive_ex(Default)]` を使用した方法
763. 手動での実装 `impl Default for T`
77
78
79# コマンドの実行方法
80
81仕様書に記載された例と説明文に相違がある場合は、例が正しく説明文の解釈にミスがあると考えてください。
82
83カレントディレクトリは初期のディレクトリから変更せず、コマンド引数で同等の事を行ってください。それが不可能な場合のみ `cd` コマンドを使用が許可されます。
84コマンドの実行に問題が発生したら、初期のカレントディレクトリに戻ってください。
85
frozenlib/mcp-attr · CLAUDE.md
@@ +1 @@
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で再生成する
@@ −1 +1 @@
1−---
2−description: Rustのコードの書き方
3−globs: *.rs
4−alwaysApply: true
5−---
1+# CLAUDE.md
62
7−# 基本方針
3+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
84
9−- Rustの慣例やベストプラクティスに沿ったコードを書きます
10−- 新しい機能を実装したり既存の機能のコードを修正した場合は、その機能のテストがあるかを確認し、無ければテストを作成します
11−- 関数名や型名は一貫性、対称性を重視します。
12−- doc commentでない通常のコメントは、理解が困難なコードにのみ付け、理解が容易なコードにはコメントを付けません
13−- エラー処理は、バグ以外でErrが返されることがないことが分かっている場合はResultを使用せず、パニックさせます
14−- コンパイラの警告が発生した場合は、なにが悪くて警告が発生しているのかを考え、実際にコードが悪いと判断された場合は修正してください
5+## Project Overview
156
16−# コンパイルエラーが発生した場合の対処
7+mcp-attrは、Model Context Protocol (MCP) サーバーを宣言的に構築するためのRustライブラリです。属性マクロを使用してMCPサーバーを簡単に作成できるように設計されています。
178
18−- 型エラーが発生したときには設計に問題がないか確認し、設計の問題に起因して型エラーが発生している場合は再設計を行います
19−- 依存関係のバージョンを下げてはなりません
20−- エラーの修正に失敗した場合は 下記の方法で情報を確認し、その情報を元にエラーの解決方法を考えてください
21− - `read_crate_readme` ツールを使用してエラーに関連する crate の readme を確認する
22− - `search_crate_source` ツールを使用してエラーに関連する型や関数を検索し、検索結果のファイルを `read_crate_file` ツールで取得して確認する
23−- 同一個所のエラーの修正に3回連続で失敗した場合はコードを元に戻し、その修正はスキップし、別の場所を修正してください
24−- スキップしたエラーのみが残っている場合は、スキップしたエラーの一覧をユーザーに提示し、ユーザーによる修正を待機してください
9+### Architecture
2510
26−# テストの書き方
11+このプロジェクトは3つのワークスペースメンバーで構成されています：
2712
28−- `tests` フォルダ内のテストでは`mod tests`は不要です。
29−- publicでない項目のテストを行う場合は、`tests/` ディレクトリにテストを配置するのではなく、実装対象のモジュール内の `tests` モジュールに書きます。
30−- `tests` モジュールは別のファイルにします。
31−- 1つのテストでのみ使用する型や関数がある場合は、テスト関数内で定義します
32−- 複数のテストを追加する際は、一つずつテストを追加し、追加したテストを実行してパスすることを確認してから次のテストを追加してください。
33−- テストを通す為だけに、テストケースの入力のみで処理を変えてはなりません
34−- テストデータを作成する際は英語のデータを作成して下さい。ただし、非ASCII文字のテストを行う場合は英語以外のデータを作成しても良いです。
13+- **mcp-attr**: メインライブラリ。MCPサーバーとクライアントの実装
14+- **mcp-attr-macros**: プロシージャルマクロの実装 (`#[mcp_server]`, `#[tool]`, `#[resource]`, `#[prompt]`)
15+- **codegen**: スキーマ生成とコード生成用のユーティリティ
3516
36−# doc commentの書き方
17+### Key Components
3718
38−- `mod xxx;` のように独立したファイルで定義されたモジュールの場合は、そのモジュールの子項目が定義されたファイルを開き、そのファイルの先頭に `//!` 形式のコメントを書きます。それ以外は項目の前に `///` 形式のコメントを書きます。
39−- 項目に属性がついている場合は、属性の後ではなく、前にコメントを書きます。
40−- ドキュメントコメントを書く際は、ソースコードや他のドキュメントコメントをよく確認し、正しい内容を書いてください。
41−- 最初の一行にはその項目を端的に表現する非常に簡潔な1行の説明を書きます
42− - 最初の一行は他の項目と同じにならないようにしてください。同じ説明文になってしまう場合は、何が違うのかを考え、それぞれに異なる説明を設定してください。
43−- 最初の一行を含め、全てのドキュメントコメントでは一貫性のある表現を使用してください
44−- 最初の1行とシグネチャからその項目の用途が充分に理解できる場合は、1行のコメントのみにしてください
45−- そうでない場合は、2行目を空行とし、3行目以降に詳細な説明と使用例を書いてください。
46−- 他の関数や型と関連性がある場合は、説明文の中で関連する関数や型の名前を [``] で囲って使用し、リンクを付けます。
47− - 例えば `XXX` 型を作成する `XXXBulder` があった場合、`XXX` 型のドキュメントには `XXXBuilder` のリンクを、`XXXBuilder` のドキュメントには `XXX` のリンクを含めます。
48− - 例えば、`XXX` 型が `fn xxx() -> XXX` の戻り値を実装する事のみが目的の場合は `XXX` 型の説明に `fn xxx` のリンクを含めます。この場合、 `fn xxx` のリンクに `XXX` を含める必要はありません。（シグネチャから自動的にリンクされるため）
19+- `#[mcp_server]` 属性によるMCPサーバーの宣言的記述
20+- `#[tool]`, `#[resource]`, `#[prompt]` 属性による機能の実装
21+- `#[complete_fn]` 属性による補完機能の実装（追加引数対応）
22+- MCPクライアント（テスト用）
23+- 型システムを活用したスキーマ生成
4924
50−## 全てのdoc commentの検証
25+### Completion Function Enhancement (`#[complete_fn]`)
5126
52−全てのドキュメントコメントを書き終わったら、下記のテストを行います。
53−書くべきドキュメントコメントが他にも残っている場合は、テストはまだ行わず、ドキュメントの作成を優先します。
27+`#[complete_fn]` 属性に追加引数機能を実装しました：
5428
55−- `cargo test --doc` を実行し、ドキュメントコメント中に含まれるコードに間違いがないか確認します
56− - 間違いがなくなるまで修正と `cargo test --doc` を繰り返します
57−- `cargo doc` を実行し、ドキュメント生成時に警告が発生しないかを確認します
58− - 警告が無くなるまで修正と `cargo doc` を繰り返します
29+#### 基本的な使用方法
30+```rust
31+#[complete_fn]
32+async fn complete_with_args(&self, value: &str, category: &str, count: Option<u32>) -> Result<Vec<String>> {
33+ // 実装
34+}
35+```
5936
60−## doc commentのテスト
37+#### 対応している引数型
38+- `&str`: 必須文字列引数
39+- `Option<&str>`: オプショナル文字列引数
40+- `T: FromStr`: 必須の型変換可能な引数
41+- `Option<T: FromStr>`: オプショナルの型変換可能な引数
6142
62−- `// #![include_doc("ファイル名", start)]`, `// #![include_doc("ファイル名", end)]`で囲まれた部分は、コマンド `rustdoc-include` を実行することで指定したファイルからコピーされます。指定されたファイルの内容を変更した後、テストを行う際は`rustdoc-include --root <ROOT_DIR>`を実行してください。このコマンドが成功した場合、何もメッセージは出力されず、終了コードが0となります。
43+#### 引数の動作
44+- 引数は `CompleteRequestParams::context::arguments` (BTreeMap) から取得
45+- オプショナル引数がない場合は `None` を返す
46+- 必須引数がない場合は空の補完結果を返す
47+- 型変換に失敗した場合はエラーを返す
48+- 型互換性チェックはコンパイル時に行われる
6349
64−## 日本語のコメントの表現
50+#### テスト
51+- 統合テスト: `tests/completion_*.rs` のマトリックス構造テスト
52+- コンパイル失敗テスト: `tests/compile_fail/completion_*.rs`
6553
66−日本語でコメントを書く場合は下記の書き方に従ってください
54+## Development Commands
6755
68−- 最初の一行では、その項目が名詞で表現できる場合は、名詞で文を終える。例えば `～の型です` ではなく `～の型` のように表現する。
56+### Build and Test
57+```bash
58+# 全パッケージのビルド
59+cargo build
6960
70−# Default の実装方法
61+# 特定パッケージのビルド
62+cargo build -p mcp-attr
63+cargo build -p mcp-attr-macros
64+cargo build -p mcp-attr-codegen
7165
72−Defaultを実装する場合は、次の順番で実装を試みてください
66+# テスト実行
67+cargo test
7368
74−1. 標準の `#[derive(Defualt)]` を使用
75−2. `derive-ex` crateの `#[derive(Ex)]` `#[derive_ex(Default)]` を使用した方法
76−3. 手動での実装 `impl Default for T`
69+# 特定パッケージのテスト
70+cargo test -p mcp-attr
7771
72+# ドキュメントテスト
73+cargo test --doc
7874
79−# コマンドの実行方法
75+# コンパイル失敗テスト（trybuild）
76+cargo test --test compile_fail -- --ignored
77+```
8078
81−仕様書に記載された例と説明文に相違がある場合は、例が正しく説明文の解釈にミスがあると考えてください。
79+### Code Quality
80+```bash
81+# 型チェック
82+cargo check
8283
83−カレントディレクトリは初期のディレクトリから変更せず、コマンド引数で同等の事を行ってください。それが不可能な場合のみ `cd` コマンドを使用が許可されます。
84−コマンドの実行に問題が発生したら、初期のカレントディレクトリに戻ってください。
84+# テストのコンパイルチェック（実行なし）
85+cargo test --no-run
8586
87+# Clippy（リンター）
88+cargo clippy
89+
90+# 自動修正
91+cargo clippy --fix --allow-dirty
92+
93+# ドキュメント生成
94+cargo doc
95+
96+# フォーマット
97+cargo fmt
98+```
99+
100+### Examples
101+```bash
102+# サンプル実行
103+cargo run --example char_count
104+cargo 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+マクロのデバッグ時：
122+1. `#[mcp_server]` を `#[mcp_server(dump)]` に変更
123+2. テスト実行でマクロ展開後コードを確認
124+3. 展開後コードを直接編集してデバッグ
125+4. 修正内容をマクロ実装に反映
126+
127+## Completion Tests Structure
128+
129+### Test File Organization
130+
131+Completion 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+```
137+tests/
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
146+Located in `tests/compile_fail/` with naming pattern: `completion_[category]_[error].rs`
147+
148+### Adding New Completion Tests
149+
150+#### For Common Functionality
151+When adding a new test for functionality that applies to all completion contexts:
152+1. **MUST add the test to all 4 matrix files** (completion_prompt_global, completion_prompt_impl, completion_resource_global, completion_resource_impl)
153+2. Use consistent test naming across all files
154+3. Only exclude from specific files if functionality is genuinely incompatible
155+4. Document any exclusions with clear comments
156+
157+#### For Special Cases
158+Use `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+
207+1. Edit the source README file (`README.md` for English, `README.ja.md` for Japanese)
208+2. Run `rustdoc-include --root .` to regenerate tests_readme.rs
209+3. Run `cargo test --doc` to verify all doctests pass
210+4. 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
216+rustdoc-include --root .
217+```
218+
219+This 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で再生成する
