feat: serve the Solr Agent Skill over MCP (SEP-2640) #280

Status: blocked. Waiting on (1) the Solr skill itself (#279) and (2) the MCP protocol updates: a spec revision that carries the Skills extension, plus MCP Java SDK and Spring AI MCP releases that implement it. See the unblock checklist.

Summary

Serve the Solr Agent Skill written in #279 to MCP clients using the Skills extension (SEP-2640, status Final, merged 2026-09-13). Serving it from the server means the skill versions with the tools it describes and reaches every client through the same connection and auth.

What SEP-2640 defines

• Each file of a skill directory is an MCP resource, conventionally at skill://<skill-path>/<file>. The last path segment must equal the skill's name.
• The server declares the resources capability plus extensions["io.modelcontextprotocol/skills"].
• Required methods: skills/list (paginated; per skill uri, verbatim frontmatter, and resources = [{uri, digest: sha256, size}] or "dynamic") and skills/get (by SKILL.md URI; -32602 if unknown). resources/directory/read is optional behind directoryRead.
• Hosts load only frontmatter up front and fetch SKILL.md and supporting files with resources/read when needed.
• Limits: 512 files and 16 MiB per skill. The SEP defines no version field (its example puts metadata.version in frontmatter) and no resource-template or subscription semantics for skills.
• A host must not treat a resource as a skill merely because of its URI scheme; a pointer in server instructions is confirmed through skills/get.

Why this is blocked (as of 2026-10-23)

• MCP Java SDK 2.0.1 has no skills/* handlers and no extensions on ServerCapabilities; 2.1.0 (released 2026-10-16) adds extensions (SEP-2133, java-sdk #1064).
• The skills/* work in flight does not cover our stdio server: java-sdk #1141 touches only the stateless server classes, and #1214 targets the 2026-07-28 "modern" server, which so far ships only in v2.2.0-M1 and has no client side. Tracking issue: #1140.
• Spring AI has no skills support in 2.0.1.
• Whether skills/* is valid on a 2025-11-25 initialize session is not settled: the SEP doesn't forbid it, but its examples are 2026-07-28 shaped.
• Client support is thin today: the official client matrix lists mcpc as full; ChatGPT, fast-agent and MCP Inspector as partial; Claude is not listed.

Unblock checklist

• feat: write a Solr Agent Skill (skills/solr) #279: the skill exists in src/main/resources/skills/solr/
• MCP protocol revision that carries the Skills extension is released and supported by our SDK line
• MCP Java SDK release with skills/* for the transports we run (stdio and stateless HTTP)
• Spring AI release that exposes it (or a verified-compatible SDK bump via the separate mcp-sdk pin in gradle/libs.versions.toml)

Planned work

• Generate the {uri, digest: sha256, size} manifest in a Gradle task from the same files resources/read serves; declare the extension capability; implement skills/list and skills/get from the manifest.
• Resource files: skill://solr/<file> with mimeType = text/markdown and audience ASSISTANT (Spring AI's @McpResource defaults to text/plain and USER). Use static URIs, not a {file} template: the SDK's matcher compiles each {var} to ([^/]+), so one template cannot match references/x.md, and templates list under resources/templates/list.
• Decide whether skill files carry @PreAuthorize("isAuthenticated()") like the existing resources in secured HTTP mode.
• Add a skill://solr/SKILL.md pointer to spring.ai.mcp.server.instructions (conflicts with docs(instructions): state that cluster infrastructure is out of scope #272 and feat(indexing): index-url — index a document set from an allow-listed http(s) URL in both transports (#208) #210, which edit the same block; under Testing: LLM-as-judge Evals for MCP tool selection #256 it triggers an eval re-run).
• SolrNativeHints: resource hint for skills/**, following its existing resource patterns.

Tests

• Every file under skills/solr/** is registered.
• resources/list + resources/read and skills/list + skills/get through McpClientIntegrationTestBase (http, stdio-jar, Docker stdio). No test reads an MCP resource over the wire today, so cover the existing solr:// resources too.
• Manifest digests match file bytes and stay within the 512-file / 16 MiB limits.
• Native: dockerIntegrationTest -Pnative covers stdio via the same base class; native-http runs only DockerImageHttpIntegrationTest, so add a resource read there or state the gap.

Open questions

• Which route: a stateful-server hook in the SDK, or moving HTTP onto the modern server?
• Which hosts let the model call resources/read itself, render skill:// resources, or honour audience?
• Does @McpResource need anything in the native image beyond the skills/** hint? Needs a native run to answer.

Acceptance criteria

• skills/list and skills/get serve the skill; every file is readable via resources/read under stdio and http, JVM and native stdio.
• spring.ai.mcp.server.instructions points at skill://solr/SKILL.md.
• ./gradlew build passes.

References

• SEP-2640: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2640-skills-extension.md
• Extension overview: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/extensions/skills/overview.mdx
• Related: feat: write a Solr Agent Skill (skills/solr) #279 (the skill), feat(indexing): index-url — index a document set from an allow-listed http(s) URL in both transports (#208) #210, Testing: LLM-as-judge Evals for MCP tool selection #256, test(eval): add the harness and Gradle task for LLM tool-selection evals #264, docs(instructions): state that cluster infrastructure is out of scope #272