Wiki source code of MCP Tool API
Last modified by gabrielc on 2026/10/21 11:18
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
13.1 | 1 | The ##MCPTool## interface (##org.xwiki.contrib.llm.mcp.MCPTool##), annotated ##@Role## and ##@Unstable##, is the extension point for contributing tools to the XWiki MCP server. |
| |
1.1 | 2 | |
| |
13.1 | 3 | The component hint is the tool's stable id, and it must be exactly the string the tool advertises as ##McpSchema.Tool.name()##. The administration tool tree and the default policy build the enabled set from hints, while registration, the ##man## catalog and the logs match on the advertised name. A hint that differs from the name silently drops the tool from every wiki: the name is never in the enabled set that registration filters on. |
 |
6.1 | 4 | |
| |
11.1 | 5 | |=Member |=Returns |=Default |=What it does |
| |
13.1 | 6 | |##getToolDefinition()## |##McpSchema.Tool## |//required// |The name, description and input JSON schema advertised to the model. The name must equal the component hint. |
| 7 | |##execute(McpSchema.CallToolRequest)## |##McpSchema.CallToolResult## |//required// |Runs one tool call and returns its result. | ||
| |
11.3 | 8 | |##isEnabled()## |##boolean## |##true## |Global kill switch: a disabled tool is registered on no wiki. |
| |
13.1 | 9 | |##isWrite()## |##boolean## |##false## |Whether the tool modifies wiki content. A tool that creates, changes or deletes content must return ##true##: the default policy leaves write tools off per wiki, and the guest variant never registers them. |
| |
11.3 | 10 | |##getCategory()## |##String## |##"General"## |The group the tool appears under in the ##man## catalog. |
| 11 | |##getSummary()## |##String## |##null## |The catalog tagline and the ##NAME## line. When ##null##, ##man## falls back to the first sentence of the definition's description. | ||
| 12 | |##getManPage()## |##String## |##null## |The long-form prose ##man## appends below the generated sections, kept out of the definition so it is not shipped on every call. | ||
| |
1.1 | 13 | |
| |
13.1 | 14 | == Contracts the signature does not show == |
| 15 | |||
| 16 | The definition is sent to the model on every request, so it stays lean. The manager meta-validates its input and output schemas at registration with the SDK's validator; a malformed schema skips that tool with a WARN instead of failing the whole server build. | ||
| 17 | |||
| 18 | ##execute## runs as the calling wiki user on the request thread. When the wiki allows guest access, that user can be the guest user, in which case the tool can read only what a guest may read. A tool whose ##isWrite()## is true is never run for a guest: the guest server variant does not register it, and ##executeWrapped## refuses it as a second line of defence. | ||
| 19 | |||
| 20 | Failure is reported as an ##isError## result whose message names the corrective action, not as an exception. The one exception is an unexpected ##RuntimeException## or ##LinkageError##, which the middleware normalizes into a generic error result so internals do not leak through the transport. | ||
| 21 | |||
| 22 | == Tool ids the server reserves == | ||
| 23 | |||
| 24 | ##man## is mandatory: it is always in the effective tool set, even when a wiki stores an explicit list that omits it. ##list_wikis## is reach-gated: it is present exactly when the wiki has cross-wiki reach enabled, and the administration tree never offers it as a toggle. Contributed tools follow the same ##isWrite()## rule as the bundled ones. The index module contributes ##list_collections## and ##search_collections## when it is installed, both under ##Semantic Search## and both read-only. | ||
| 25 | |||
| 26 | The full list of tools, bundled and contributed, is on [[MCP Tools>>doc:documentation.extensions.user.llm.mcp-server.tools.WebHome]]. [[Create a New MCP Tool>>doc:documentation.extensions.dev.llm.mcp-server.create-mcp-tool.WebHome]] shows the component skeleton those two required members go in. |
