Spring Docs

🍃 Spring Documentation MCP Server

🚀 強化版 v1.4.1： Spring AI のサポート、インテリジェントなキャッシュ、高度なチュートリアル、Spring エコシステムへの包括的なアクセスを備えた強力な 17 個のツール

🌐 あらゆる MCP クライアントとの互換性： Claude Code、Gemini CLI、VS Code、JetBrains IDE、その他すべての MCP 互換クライアントで動作します！

🎯 クイックスタート

🔌 あらゆる MCP クライアントとの互換性

このサーバーはすべての MCP 互換クライアントで動作します。

Claude Desktop/Code

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"],
      "description": "Spring Documentation MCP Server with 17 powerful tools"
    }
  }
}

Gemini CLI

mcp_servers:
  spring-docs:
    command: "npx"
    args: ["@enokdev/springdocs-mcp@latest"]
    description: "Spring Documentation Server"

VS Code MCP Extension

{
  "mcp.servers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"]
    }
  }
}

あらゆる MCP クライアント（NPX）

npx @enokdev/springdocs-mcp@latest

グローバルインストール（すべてのクライアント）

npm install -g @enokdev/springdocs-mcp
# Then use: springdocs-mcp

Docker（近日公開 - Docker MCP Catalog）

# Via Docker MCP CLI (when available in catalog)
docker mcp add springdocs-mcp

# Via Docker directly
docker pull mcp/springdocs-mcp:latest
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \
  docker run -i mcp/springdocs-mcp:latest

Docker 配布のメリット：

• 暗号署名と SBOM によるセキュリティの強化
• 分離された実行環境
• Docker Desktop でのトークン使用量の削減
• セキュリティ更新の自動適用

設定ファイルの場所：

• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） / %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Claude Code： ~/.claude-code/mcp-config.json
• VS Code： ~/.vscode/mcp-settings.json
• JetBrains IDE： .jetbrains/mcp-config.json

---

✨ 機能とツール

このサーバーは17 個のツールを提供します。

📚 コアドキュメント（8 個のツール）

ツール	用途	使用例
search_spring_docs	Spring ドキュメントを検索します（docType は all、guides、projects、reference、content。version は任意）	「WebClient のドキュメントを検索」
search_spring_projects	Spring プロジェクトを探します	「セキュリティ関連のプロジェクトを探す」
get_spring_project	プロジェクトページを Markdown 形式で取得します（offset によるページネーションに対応）	「Spring Data プロジェクトを表示」
get_all_spring_guides	入門ガイドの一覧を取得します	「ガイドの一覧を表示」
get_spring_guide	ガイドの全内容を取得します	「rest-service ガイドを取得」
get_spring_reference	11 個のプロジェクトのリファレンスドキュメントを取得します（version、offset）	「Boot リファレンスの web セクション」
get_migration_guide	Spring Boot／Framework／Batch の移行ガイドとアップグレードに関する注意事項を取得します	「Boot 3.4 への移行ガイド」
search_spring_concepts	Spring の概念を調べます（version は任意）	「自動構成について説明」

🚀 高度な機能（6 個のツール）

ツール	用途	使用例
search_spring_ecosystem	Spring AI を含むエコシステム全体を検索します	「Spring AI のベクトルストアを探す」
get_spring_tutorial	手順ごとのチュートリアルを取得します	「Spring Security のチュートリアル」
compare_spring_versions	バージョンの比較と移行に関する注意事項を取得します	「3.3 と 3.4 を比較」
get_release_notes	フォーカスフィルターを適用して GitHub のリリースノートを取得します	「Boot 3.5 のリリースノート」
get_spring_best_practices	カテゴリ別の専門的なガイダンスを取得します	「テストのベストプラクティス」
diagnose_spring_issues	オフラインでスタックトレースとエラーを診断します	「この DataSource エラーを診断」

🧰 ツール（3 個のツール）

ツール	用途	使用例
get_spring_initializr	Spring Initializr のメタデータを取得します：Boot のバージョン、依存関係（start.spring.io）	「Initializr ではどの Boot バージョンを選べますか？」
find_spring_dependency	要件に合うスターターを探し、Maven と Gradle のコード例を提示します（bootVersion は X.Y.Z 形式で指定。任意）	「Redis キャッシュにはどの依存関係が必要ですか？」
spring_cache_stats	インメモリキャッシュの統計を取得し、必要に応じてキャッシュを消去します	「キャッシュの統計を表示」

---

📎 リソース

• spring://project/<slug>：Spring プロジェクトのページを完全な Markdown として取得します（例：spring://project/spring-boot）。resources/list はレジストリ内の 11 個のプロジェクトを列挙します。テンプレートでは spring.io の任意のプロジェクトを指定できます。
• spring://guide/<id>：Spring の入門ガイドを完全な Markdown として取得します（例：spring://guide/rest-service）。リソーステンプレートから利用できます。

💬 プロンプト

• migrate-boot-version（to_version、任意の from_version）：get_migration_guide、get_release_notes、get_spring_reference を連鎖させて、Spring Boot のアップグレードを計画します。
• explain-error（error_message、任意の stack_trace）：diagnose_spring_issues と get_spring_reference を連鎖させて、Spring のエラーを説明します。

📖 使用例

基本的な検索

"Search for REST API documentation in Spring Boot"

search_spring_docs と search_spring_concepts では、任意の version を指定できます（3.4 または 3.4.2。パッチバージョンは無視されます。current または省略時は最新バージョン）。指定したバージョンの Spring Boot リファレンスドキュメントが対象になります（公開されていないバージョンを指定すると、専用のエラーが返されます）。ガイドとプロジェクトはバージョン管理されておらず、この指定は無視されます。docType=content の場合、他のバージョンの Boot リファレンスページは検索結果から除外されます。

get_migration_guide では project を指定できます（デフォルトは spring-boot、ほかに spring-framework、spring-batch）。Framework ではマイナーバージョンのリリースノート（6.2、「Upgrading From ...」セクション）が、Batch では移行ガイド（5.0、6.0）が提供されます。どちらもプロジェクトの Wiki から生の Markdown として読み取られます。Boot と同様に、section と offset を指定できます。Spring Security と Spring AI（docs.spring.io のページ）はまだ対象外です。

search_spring_docs では docType=content を指定できます。これは、サーバーがすでに読み取ったページ（get_spring_project、get_spring_reference、get_spring_guide）を対象とした全文検索（BM25 ランキング）です。docType=all にも含まれ、ページが読み取られるまでは空のままです。

🆕 Spring AI のサポート

"Get Spring AI ChatClient reference documentation"
"Search for RAG and embeddings in Spring AI"
"Show me Spring AI vector store documentation"
"Find Spring AI LLM integration examples"

エコシステムの探索

"Search the Spring ecosystem for microservices patterns"

学習パス

"Get a beginner tutorial for REST API development"

問題解決

"Diagnose 'Failed to configure DataSource' error"

移行計画

"Compare Spring Boot 2.7.0 and 3.0.0 breaking changes"

ベストプラクティス

"Get architecture best practices for expert developers"

---

🔧 詳細設定

パフォーマンスの最適化

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"],
      "env": {
        "NODE_OPTIONS": "--max-old-space-size=4096",
        "REQUEST_TIMEOUT": "15000",
        "MAX_RETRIES": "3"
      }
    }
  }
}

企業／プロキシ環境

{
  "mcpServers": {
    "spring-docs": {
      "command": "npx",
      "args": ["@enokdev/springdocs-mcp@latest"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

---

HTTP トランスポート（任意）

デフォルトでは、サーバーは stdio で通信します。ローカルまたはコンテナーでホストするには：

npx @enokdev/springdocs-mcp --transport http --port 3000   # écoute sur 127.0.0.1

オプション	変数	デフォルト
--transport stdio|http	MCP_TRANSPORT	stdio
--port	MCP_PORT	3000
--host	MCP_HOST	127.0.0.1
（なし）	MCP_ALLOWED_HOSTS	空：追加の Host をカンマ区切りで指定

MCP エンドポイント：POST /mcp（ステートレスモード）。ヘルスチェック：GET /healthz。認証はありません。デフォルトではループバックでのみリッスンし、Host／Origin ヘッダーを DNS リバインディングに対して検証します。コンテナーでは、ポートを公開したうえで MCP_TRANSPORT=http MCP_HOST=0.0.0.0 を指定します（-p 127.0.0.1:3000:3000）。公開ポートが内部ポートと異なる場合は、たとえば MCP_ALLOWED_HOSTS=localhost:8080 のように、クライアントが使用する Host を指定してください。

Host は 名前:ポート の形式で指定する必要があります。リバースプロキシの背後でクライアントがポート 80 または 443 を使用する場合など、ポートのない Host（例：Host: mcp.example.com）は 403 で拒否されます。その場合は、プロキシが転送する形式で MCP_ALLOWED_HOSTS=mcp.example.com に指定してください（カンマ区切りのリスト。受信したヘッダーと完全一致で比較されます）。

GitHub トークン（任意）

get_release_notes と compare_spring_versions は GitHub API に問い合わせます。認証なしの場合、リクエスト数は 1 時間あたり 60 回に制限されています。GITHUB_TOKEN を設定すると（特別なスコープのないトークンで十分です）、この制限は 1 時間あたり 5000 回に引き上げられます。トークンは api.github.com にのみ送信され（他のホストやリダイレクト先には送信されません）、ログに記録されることもありません。レート制限に達した場合、ツールは待機せず、再試行可能な時間を含む明確なメッセージを表示して直ちに失敗します。get_release_notes では、version に X.Y（例：3.5）を指定すると、そのマイナーバージョンの最新の安定版リリースを取得できます。compare_spring_versions では、focus（breaking-changes、new-features、deprecations）を適用します。

{ "mcpServers": { "springdocs": { "command": "npx", "args": ["@enokdev/springdocs-mcp@latest"], "env": { "GITHUB_TOKEN": "ghp_..." } } } }

🧪 テストと開発

クイックテスト

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx @enokdev/springdocs-mcp@latest

開発環境のセットアップ

git clone https://github.com/tky0065/springdocs-mcp.git
cd springdocs-mcp
npm install
npm run build
npm test

負荷テスト

# Test multiple tools quickly
for tool in "search_spring_docs" "search_spring_projects" "search_spring_ecosystem"; do
  echo "Testing $tool..."
  echo "{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\", \"params\": {\"name\": \"$tool\", \"arguments\": {\"query\": \"test\", \"limit\": 2}}}" | npx @enokdev/springdocs-mcp@latest > /dev/null
done

---

🆘 トラブルシューティング

よくある問題と解決策

「サーバーの起動に失敗しました」

# Check Node.js version (requires 20.18.1+)
node --version

# Update to latest
npm update -g @enokdev/springdocs-mcp

# Clear cache
npm cache clean --force

「ツールが応答しません」

# Test connectivity
curl -I https://spring.io

# Check Claude Desktop config syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

「パフォーマンスが遅い」

• キャッシュを有効にします（v1.2.3 以降では自動）
• 範囲の広い検索ではなく、具体的なクエリを使用します
• メモリを増やします：NODE_OPTIONS="--max-old-space-size=4096"

「ポート 8080 はすでに使用されています」（Spring Boot のエラー）

解決策： application.properties でポートを変更します：

server.port=8081

「DataSource の設定に失敗しました」

解決策：

1. pom.xml にデータベースの依存関係を追加します
2. application.properties でデータソースを設定します
3. 自動設定を除外します：@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})

ヘルスチェック スクリプト

#!/bin/bash
echo "🔍 Testing Spring MCP Server..."

# Test server startup
timeout 10s echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx @enokdev/springdocs-mcp@latest > /dev/null
echo $? -eq 0 && echo "✅ Server: OK" || echo "❌ Server: FAILED"

# Test network
curl -s --max-time 5 https://spring.io > /dev/null
echo $? -eq 0 && echo "✅ Network: OK" || echo "❌ Network: FAILED"

---

📊 v1.2.3 の新機能

🆕 主な機能強化

• Spring エコシステムに幅広くアクセスできる、高度な新しいツールを 5 つ追加
• 繰り返しのリクエストをメモリ内にキャッシュ（TTL は 30 分、安定したコンテンツは 24 時間）
• 指数バックオフによる自動再試行と、5 MiB のレスポンスサイズ上限
• モジュール化されたサービスと最適化されたコードによる、クリーンなアーキテクチャ

🎯 新機能

• プロジェクト、ガイド、ドキュメント、API を横断するエコシステム全体の検索
• 初級・中級・上級レベルに対応した段階的なチュートリアル
• 詳細な移行ガイダンスを含むスマートなバージョン比較
• ドメインと経験レベルで分類された、専門家によるベストプラクティス
• Spring Boot のよくある問題を対象とした、インテリジェントな診断

⚡ パフォーマンスと耐障害性

• 繰り返しのリクエストは、新たなネットワーク呼び出しを行わず、メモリ内キャッシュから返されます（TTL は 30 分、安定したコンテンツは 24 時間）
• キャッシュは推定メモリ使用量の上限で制御されます（デフォルトは 64 MiB、LRU による削除、上限を超える単一の値はキャッシュされません）。MCP_CACHE_MAX_MB で上書きできます（例：MCP_CACHE_MAX_MB=32）。spring_cache_stats は、エントリー数と推定メモリ使用量／上限を報告します
• すべての外部 HTTP 呼び出しに、指数バックオフによる再試行とリクエストタイムアウトを適用
• 5 MiB を超えるレスポンスは拒否されます

---

🔮 ロードマップ

v1.5.0（次期）

• インタラクティブな Spring Boot プロジェクトジェネレーター（Initializr のメタデータと依存関係の検索機能はすでに利用可能）
• カスタムチュートリアルの作成

v1.6.0（将来）

• AI を活用したコード提案
• パフォーマンスのボトルネック検出
• セキュリティ脆弱性のスキャン
• 自動テストの推奨

---

🤝 コントリビューションとサポート

クイックリンク

• 課題： https://github.com/tky0065/springdocs-mcp/issues
• ディスカッション： https://github.com/tky0065/springdocs-mcp/discussions
• NPM パッケージ： https://www.npmjs.com/package/@enokdev/springdocs-mcp

ヘルプの利用方法

1. GitHub で既存の課題を検索します
2. エラーメッセージと再現手順を含む、詳細な課題を作成します
3. 質問や機能リクエストについて、コミュニティのディスカッションに参加します

開発

# Setup development environment
git clone https://github.com/tky0065/springdocs-mcp.git
cd springdocs-mcp
npm install
npm run build

# Run tests
npm test
./test-enhanced.sh

# Submit PR
git checkout -b feature/your-feature
# Make changes
git commit -m "feat: add your feature"
git push origin feature/your-feature

🌐 CLI 統合の例

Claude Code

# Direct usage
claude-code --mcp-server "npx @enokdev/springdocs-mcp@latest"

# With config file
claude-code --mcp-config claude-mcp-config.json

Gemini CLI

# Direct integration
gemini --mcp-server "npx @enokdev/springdocs-mcp@latest"

# With YAML config
gemini --mcp-config gemini-config.yaml

# Environment variable
export GEMINI_MCP_SERVERS='[{"name":"spring-docs","command":"npx","args":["@enokdev/springdocs-mcp@latest"]}]'
gemini "Search for Spring Boot security documentation"

カスタム API 統合

// Express.js API Gateway example
const { spawn } = require('child_process');

app.post('/spring-docs/:tool', async (req, res) => {
    const mcp = spawn('npx', ['@enokdev/springdocs-mcp@latest']);
    const request = {
        jsonrpc: "2.0",
        id: Date.now(),
        method: "tools/call",
        params: {
            name: req.params.tool,
            arguments: req.body
        }
    };
    mcp.stdin.write(JSON.stringify(request));
    // Handle response...
});

互換性テスト

# Test MCP protocol handshake
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | npx @enokdev/springdocs-mcp@latest

# Test tools listing
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | npx @enokdev/springdocs-mcp@latest

# Test tool execution
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search_spring_projects", "arguments": {"query": "boot", "limit": 1}}}' | npx @enokdev/springdocs-mcp@latest

---

📄 ライセンスと謝辞

ライセンス： MIT - LICENSE ファイルを参照してください

謝辞：

• 優れたドキュメントを提供してくださった Spring Framework Team
• Model Context Protocol を提供してくださった Anthropic
• 継続的にサポートしてくださった Spring Community

---

🚀 インテリジェンスとパフォーマンスを強化して、Spring エコシステムを探索しましょう！

🌐 あらゆる MCP と互換： Claude Code、Gemini CLI、VS Code、JetBrains IDE、その他あらゆる MCP 対応クライアントでシームレスに動作します！

❤️ を込めて EnokDev が作成