From ddc85959ce8e1790c2f51d6092e3f1e46caf36a8 Mon Sep 17 00:00:00 2001 From: Sandking Date: Tue, 30 Jun 2026 16:07:43 +0800 Subject: [PATCH] Clarify README SDK boundary --- README.md | 36 +++++++++++++++++++++++------------- README.zh-CN.md | 27 +++++++++++++++++---------- 2 files changed, 40 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 10beae3..25a1474 100644 --- a/README.md +++ b/README.md @@ -48,14 +48,23 @@ Implemented now: `sse`, or `stdio`, and publishes only the primary safe `ToolCallbackProvider` - Unit tests and GitHub Actions CI -Not implemented yet: +Outside this SDK's current ownership unless a future module explicitly scopes it: -- FastMCP-owned MCP server implementation -- End-to-end validation for AG-UI SSE stream and the tool event chain +- FastMCP-owned MCP server implementation, public MCP service catalogs, or real + production MCP endpoints +- Application-level AG-UI, CopilotKit, SSE tool-event streams, logs, and frontend + event payloads; this SDK does not emit or inspect those events - Resources and prompts - Plain classpath package scanning outside Spring - Full authentication flows, OAuth, secret lifecycle, and production middleware -- Protocol conformance tests + owned by the consuming application or MCP server +- Full protocol conformance tests for third-party MCP servers + +This repository's tests use local fake MCP servers to validate the SDK contract: +managed client creation, initialization and tool listing, HTTP headers, query +params, cookie/session behavior, virtual tool schemas, protected-argument +injection, and raw-tool hiding. Consuming applications own real MCP smoke tests +against their private deployments, plus any AG-UI/frontend/log leak checks. ## Safe core @@ -251,12 +260,13 @@ The reusable Spring Boot binding code lives in `FastMcpSafeProperties` and `FastMcpSafeConfigurationFactory`, but it is not a standalone Agent framework starter and does not create MCP clients by itself. -## Production integration checklist +## Application integration checklist -Production validation does not require FastMCP Java to implement the MCP -protocol. It validates that the safety wrapper remains the only model-facing -tool path when Spring AI, AgentScope, and the underlying MCP SDKs run against a -real MCP service. +This is an application-owned checklist, not a claim that FastMCP Java ships a +complete production MCP platform. Production validation does not require this +SDK to implement the MCP protocol. It validates that the safety wrapper remains +the only model-facing tool path when Spring AI, AgentScope, and the underlying +MCP SDKs run against a real MCP service. Before using a configured server in production: @@ -414,10 +424,10 @@ integration paths: `ToolContext`. - `fastmcp-examples/spring-ai-boot-starter`: binds `fastmcp.safe.*`, declares resolver beans such as `currentUserId`, and verifies that the starter publishes the - primary `fastMcpSafeToolCallbackProvider` from an existing raw provider. The - managed MCP client path, including streamable HTTP transport and per-server raw - provider scoping, is covered by starter tests until a real MCP server example is - added. + primary `fastMcpSafeToolCallbackProvider` from an existing raw provider and a + local fake `streamable-http` MCP server. The examples do not require or publish + real MCP endpoints; deployment-specific smoke tests belong to consuming + applications. Run all examples with: diff --git a/README.zh-CN.md b/README.zh-CN.md index aa1355a..dec5ed3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -42,14 +42,20 @@ MCP raw tools clients，并且只发布 primary 的安全 `ToolCallbackProvider` - Unit tests 和 GitHub Actions CI -尚未实现： +不属于本 SDK 当前职责，除非未来明确新增对应模块： -- 本库自己的 MCP server implementation -- AG-UI SSE stream 和 tool event 链路的端到端验证 +- 本库自有 MCP server implementation、公开 MCP 服务列表或真实生产 MCP endpoint +- 应用层 AG-UI、CopilotKit、SSE tool event、日志和前端事件 payload；本 SDK 不产生也不审查这些事件 - Resources 和 prompts - Spring 之外的普通 classpath package scanning -- 完整 authentication flow、OAuth、secret lifecycle 和 production middleware -- Protocol conformance tests +- 宿主应用或 MCP server 自己负责的完整 authentication flow、OAuth、secret lifecycle 和 production middleware +- 面向第三方 MCP server 的完整 protocol conformance tests + +本仓库测试使用本地 fake MCP server 验证 SDK contract：managed client 创建、 +初始化和工具列表、HTTP headers、query params、cookie/session 行为、 +virtual tool schema、protected-argument injection，以及 raw tool 隐藏。 +接入方负责在自己的私有部署上执行真实 MCP smoke test，并负责 AG-UI、前端 +事件和日志侧的泄露检查。 ## Safe core @@ -239,11 +245,11 @@ starter 或应用自身提供 `Toolkit`；本库不负责创建 AgentScope agent `FastMcpSafeProperties` 和 `FastMcpSafeConfigurationFactory`，但它不是独立的 Agent 框架 starter，也不会自行创建 MCP client。 -## 生产接入检查清单 +## 应用接入检查清单 -生产验证并不要求 FastMCP Java 自己实现 MCP 协议。它要验证的是：当 Spring AI、 -AgentScope 和底层 MCP SDK 连接真实 MCP 服务时，安全包装层仍然是唯一面向模型的 -tool 路径。 +这是应用侧清单，不是 FastMCP Java 已提供完整生产 MCP 平台的声明。生产验证并不要求 +本 SDK 自己实现 MCP 协议。它要验证的是：当 Spring AI、AgentScope 和底层 MCP SDK +连接真实 MCP 服务时，安全包装层仍然是唯一面向模型的 tool 路径。 在生产使用某个配置 server 前，应至少核对： @@ -386,7 +392,8 @@ ToolCallbackProvider safeProvider = FastMcpSpringAiTools.wrap(rawProvider, List. - `fastmcp-examples/spring-ai-boot-starter`：绑定 `fastmcp.safe.*`，声明 `currentUserId` / `currentTenantId` 等 resolver bean，并验证 starter 基于已有 raw provider 或本地 fake `streamable-http` MCP server 发布 primary 的 - `fastMcpSafeToolCallbackProvider`，模型只看到 safe virtual tool。 + `fastMcpSafeToolCallbackProvider`，模型只看到 safe virtual tool。示例不要求也不发布 + 真实 MCP endpoint；部署相关 smoke test 由接入应用负责。 运行全部示例：