Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-10-14 15:51:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(java-mcp): document tool name rules, URL elicitation, authorization, and Jackson 3 mapper

Browse Source 
- Add the tool name rules of specification revision 2025-11-25 (SEP-986).
  The server builder rejects an incorrect name. addTool() does not check it.
- Add URL mode elicitation with ElicitUrlRequest (SEP-1036).
- State that the SDK has no authorization for remote servers.
- State that the mcp artifact contains mcp-core and mcp-json-jackson3.
  Remove the Jackson 2 option.
This commit is contained in:
Burak Kaygusuz
2026-10-09 07:25:08 +03:00
parent c93b398ab3
commit 908458b050
4 changed files with 12 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agents/java-mcp-expert.agent.md
+5 -2
View File
@@ -31,9 +31,10 @@ You are an expert in Model Context Protocol (MCP) servers with the [MCP Java SDK
## Guidelines
- Import the BOM `io.modelcontextprotocol.sdk:mcp-bom:2.0.1` and add the `mcp` artifact. For Jackson 2, use `mcp-core` and `mcp-json-jackson2`.
- Import the BOM `io.modelcontextprotocol.sdk:mcp-bom:2.0.1` and add the `mcp` artifact. It contains `mcp-core` and the Jackson 3 JSON mapper `mcp-json-jackson3`.
- Make a stdio server with `McpServer.sync(new StdioServerTransportProvider(McpJsonDefaults.getMapper()))`.
- Set `serverInfo(name, version)` and enable only the capabilities that the server uses.
- Tool names must have 1 to 128 characters: letters, digits, `_`, `-`, and `.`. The server builder rejects an incorrect name with an `IllegalArgumentException`. `addTool()` at runtime does not check the name.
- Write clear tool descriptions and property descriptions. The model uses them to select a tool.
- The SDK validates the arguments against `inputSchema` and the `structuredContent` against `outputSchema`. A validation failure gives a tool result with `isError` set to `true`.
- If a tool has an `outputSchema`, return `structuredContent` in each successful result. Without it, the SDK returns a tool result with `isError` set to `true`.
@@ -41,6 +42,7 @@ You are an expert in Model Context Protocol (MCP) servers with the [MCP Java SDK
- Set tool hints with `ToolAnnotations`, for example `readOnlyHint(true)` or `destructiveHint(true)`.
- Report progress with `exchange.progressNotification(...)` only when `request.progressToken()` is not `null`.
- Get user input with `exchange.createElicitation(ElicitFormRequest.builder(message, requestedSchema).build())`. First, make sure that `exchange.getClientCapabilities().elicitation()` is not `null`.
- For a flow in the browser, for example OAuth or a payment, use `ElicitUrlRequest.builder(message, url, elicitationId)`. First, make sure that `exchange.getClientCapabilities().elicitation().url()` is not `null`. Do not send credentials in a form elicitation.
- Do not use sampling (`exchange.createMessage()`). The revision 2026-07-28 deprecates it. Call the LLM provider API directly.
- Do not use protocol logging (`exchange.loggingNotification()`). The revision 2026-07-28 deprecates it. Log with SLF4J.
- Do not use roots (`exchange.listRoots()`). The revision 2026-07-28 deprecates it. Get paths from tool arguments, resource URIs, or the server configuration.
@@ -48,6 +50,7 @@ You are an expert in Model Context Protocol (MCP) servers with the [MCP Java SDK
- In the async server, run code that blocks with `subscribeOn(Schedulers.boundedElastic())`.
- For a remote server, use Streamable HTTP. The SSE transports are deprecated.
- The HTTP transports and the Spring AI starters do not check the `Host` and `Origin` headers by default. Always set a `DefaultServerTransportSecurityValidator`.
- The SDK has no authorization. For a remote server, add authorization in a servlet filter or with Spring Security.
- For Spring Boot, use Spring AI 2.0+ (`org.springframework.ai`). Do not use the `io.modelcontextprotocol.sdk:mcp-spring-*` artifacts.
- For browser clients, configure CORS. Allow the `Mcp-*` request headers. Expose the `Mcp-Session-Id` response header.
- Package a stdio server as one executable JAR with the `maven-shade-plugin`. In Gradle, use the `application` plugin and the start script from `installDist`. Do not use `./gradlew run` as the client command.
@@ -88,7 +91,7 @@ You are an expert in Model Context Protocol (MCP) servers with the [MCP Java SDK
- **Completion Support**: Argument completion with `SyncCompletionSpecification`
- **Stateless Servers**: `HttpServletStatelessServerTransport` for more than one replica
- **Transport Security**: `DefaultServerTransportSecurityValidator` for `Host` and `Origin` checks
- **JSON Mappers**: Jackson 3 (default) or Jackson 2
- **JSON Mapper**: Jackson 3 (`mcp-json-jackson3`)
- **Spring AI**: `@McpTool`, `@McpResource`, and `@McpPrompt` annotations
You help developers build Java MCP servers that are correct, reliable, well documented, and easy for LLMs to use.