Solesonic MCP Server

🚀 solesonic-mcp-server

這是一個基於Spring AI的Spring Boot應用程序，它提供了一個HTTP模型上下文協議（MCP）服務器。本README將介紹如何運行該服務器，以及如何設置MCP客戶端以連接到它。

🚀 快速開始

🔍 前提條件

• JDK 24+
• Maven 3.9+
• AWS Cognito（或其他能夠頒發具有預期受眾和範圍的JWT的OAuth2提供商）

應用程序配置為在運行時使用spring-dotenv從本地的.env文件加載環境變量。

⚙️ 配置環境

在項目根目錄下創建或編輯.env文件（該文件已被git忽略）：

COGNITO_ISSUER_URI=https://example.auth.<region>.amazoncognito.com
# 如有需要，可選擇覆蓋JWK集URI
# COGNITO_JWK_SET_URI=https://cognito-idp.<region>.amazonaws.com/<userPoolId>/.well-known/jwks.json

src/main/resources/application.properties中的相關屬性：

spring.application.name=solesonic-mcp-server
spring.ai.mcp.server.name=solesonic-mcp-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.type=sync
spring.ai.mcp.server.capabilities.tool=true

# OAuth2資源服務器（AWS Cognito）
spring.security.oauth2.resourceserver.jwt.issuer-uri=${COGNITO_ISSUER_URI}
spring.security.oauth2.resourceserver.jwt.jwk-set-uri=${COGNITO_JWK_SET_URI}
spring.security.oauth2.resourceserver.jwt.audiences=api://solesonic-mcp

注意：

• 操作系統環境變量會覆蓋.env文件中的值。
• 無需額外的標誌，.env文件會在啟動時自動加載。

🛠️ 構建和運行

# 構建
mvn package

# 運行（如有需要，請調整jar包名稱）
java -jar target/solesonic-mcp-server-0.0.1-SNAPSHOT.jar

默認基礎URL：http://localhost:8080

🔐 認證和授權

此服務器作為OAuth2資源服務器（JWT）受到保護，所有請求都需要有效的Bearer令牌。

• 預期受眾：api://solesonic-mcp（請參閱application.properties）
• 所需範圍：MCP_INVOKE
  • Spring Security會將OAuth範圍映射為帶有SCOPE_前綴的權限。代碼會檢查SCOPE_MCP_INVOKE。

重要提示：當前的SecurityConfig會保護所有端點。如果您希望/actuator/health公開訪問，請相應地調整安全配置。按照現狀，所有請求都必須提供有效的令牌。

📡 MCP端點

本項目使用Spring AI MCP Server（WebMVC）啟動器，它會在/mcp下提供一個HTTP MCP端點。

• 基礎MCP HTTP端點：POST http://localhost:8080/mcp
• 傳輸協議：HTTP（根據MCP HTTP傳輸協議定義的基於HTTP的JSON-RPC）
• 工具：此示例註冊了一個名為message_me的簡單工具，它會回顯消息。

🎫 從Cognito獲取令牌（客戶端憑證示例）

您需要一個包含MCP_INVOKE範圍和受眾api://solesonic-mcp的令牌。

# 1) 使用客戶端憑證獲取令牌（值為示例，請替換佔位符）
TOKEN=$(curl -s \
  -u <clientId>:<clientSecret> \
  -d "grant_type=client_credentials&scope=MCP_INVOKE" \
  https://<your-domain>.auth.<region>.amazoncognito.com/oauth2/token \
  | jq -r .access_token)

echo "$TOKEN" | head -c 20; echo

# 2) 使用令牌調用MCP端點（檢查器/客戶端通常會執行握手；這是一個健全性檢查）
curl -i \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  http://localhost:8080/mcp \
  --data '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}},"meta":{}}'

如果收到401/403錯誤，請參閱下面的故障排除部分。

🖥️ 設置此MCP服務器的客戶端

以下是將客戶端連接到此MCP服務器的兩種簡單方法。

選項A：MCP檢查器（CLI）

MCP檢查器是一個方便的交互式測試工具。 要求：Node.js 18+

# 通過npx安裝並運行
npx @modelcontextprotocol/inspector \
  --server http \
  --url http://localhost:8080/mcp \
  --header "Authorization: Bearer $TOKEN"

這將執行MCP握手，並允許您檢查message_me等工具。

選項B：Claude桌面版（HTTP MCP服務器）

Claude桌面版支持MCP服務器。您可以使用頭部信息註冊一個HTTP MCP服務器。

1. 打開Claude桌面版的MCP配置文件（因操作系統而異）。例如，在macOS上：

• ~/Library/Application Support/Claude/mcp.json

2. 為此服務器添加一個條目。示例片段：

{
  "mcpServers": {
    "solesonic-mcp-server": {
      "transport": "http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer ${SOLESONIC_MCP_TOKEN}"
      }
    }
  }
}

3. 在啟動Claude桌面版之前，使用您的令牌設置一個環境變量：

• macOS/Linux：export SOLESONIC_MCP_TOKEN="$TOKEN"
• Windows（PowerShell）：$env:SOLESONIC_MCP_TOKEN = "$TOKEN"

4. 重啟Claude桌面版。您應該會看到solesonic-mcp-server MCP提供程序可用，並且有message_me工具。

注意：

• 如果您使用的Claude桌面版尚不支持帶有頭部信息的HTTP MCP，您可以選擇運行一個小型本地代理來注入授權頭部，或者使用MCP檢查器進行測試。

💻 使用示例

基礎用法

使用連接的客戶端，通過傳遞消息參數調用message_me工具，它會將消息回顯回來。

🐞 故障排除

• 401未授權
  • 令牌缺失、過期或不是由配置的Cognito issuer-uri頒發的。
  • JWKS URL無法訪問或配置錯誤。
• 403禁止訪問
  • 令牌有效，但缺少所需的MCP_INVOKE範圍。請確保您的OAuth客戶端被允許請求該範圍，並且Cognito在訪問令牌中包含該範圍。
• 受眾不匹配
  • 請確保令牌的受眾與api://solesonic-mcp匹配，或者相應地調整application.properties。
• 連接問題
  • 驗證應用程序是否在http://localhost:8080上監聽，並且/mcp是否可以訪問。

📝 注意事項

• .env文件僅用於本地開發。實際的操作系統環境變量會覆蓋.env文件中的值。
• .env文件已被git忽略，以防止提交敏感信息。

🚧 正在進行的工作

有關正在進行的增強功能、當前狀態和路線圖，請參閱即時文檔：

• IN_PROGRESS.md