金大哥 - solesonic-mcp-server MCP 详情

article

README

🚀 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服务器。

打开Claude桌面版的MCP配置文件（因操作系统而异）。例如，在macOS上：

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

为此服务器添加一个条目。示例片段：

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

在启动Claude桌面版之前，使用您的令牌设置一个环境变量：

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

重启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

solesonic-mcp-server