meirborowski/Lodestone / .claude/skills/add-mcp-tool
add-mcp-tool
VerifiedAdd an MCP tool to the Lodestone editor, so AI agents can use a new editor feature - the tool's schema and handler, the command it runs, and its in-process tests. Use whenever an editor-facing feature lands (every editor action needs an MCP tool), or when an agent needs something the tools can't do.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.2 KB |
SKILL.md
View on GitHub---
name: add-mcp-tool
description: Add an MCP tool to the Lodestone editor, so AI agents can use a new editor feature - the tool's schema and handler, the command it runs, and its in-process tests. Use whenever an editor-facing feature lands (every editor action needs an MCP tool), or when an agent needs something the tools can't do.
---
# Add an MCP Tool
Everything a person can do in the editor, an agent must be able to do through MCP (see `docs/AIControl.md` and `docs/Decisions/0016-mcp-server.md`). Components don't need tools: the generic component tools cover every registered component. Tools are for features that aren't components - play mode, screenshots, export, multiplayer, and so on.
## 1. Put the behaviour in the editor context or a command
- Anything that changes a document is a `Command` (`Source/Editor/Lodestone/Editor/Commands`), run through `EditorContext::Execute()`, so it can be undone and the UI can use it too. It must change nothing when it fails, and give the same result - UUIDs included - when redone
- Anything else that the UI also does (opening documents, play mode) is a method on `EditorContext`, so the UI and MCP share it. Tools stay thin
## 2. Register the tool
In `Source/Editor/Lodestone/Editor/Mcp/EditorTools.cpp`, in the `Add...Tools()` function for its area:
```cpp
server.AddTool({.Name = "light_bake",
.Title = "Bake lighting",
.Description = "Bakes the open scene's lighting. Returns how long it took",
.InputSchema = Schema(R"({"type": "object", "properties": {
"quality": {"type": "string", "enum": ["draft", "final"], "description": "draft by default"}}})"),
.Handler = [&context](const Json::Value& json)
{
const auto quality = Arguments(json).OptionalString("quality");
if (!quality)
return Fail(quality.error());
...
return McpToolResult::Structured({{"seconds", seconds}});
}});
```
- Names are `snake_case`, `<area>_<verb>`. The schema is a JSON Schema object with a description for anything that isn't obvious; required arguments are listed in `required`
- Read arguments with `Arguments`, which reports which argument is wrong. Return `Fail(error)` or `McpToolResult::Failure()` for anything the agent can fix - never throw, and never assert on agent input
- Set `ReadOnly` for tools that only read, and `Destructive` for tools that delete or discard. Tools that replace the open document check `CheckUnsaved()` and take `discardChanges`
- Return structured content for data (`McpToolResult::Structured`), `Run()` for commands (it reports what was done), and `McpToolResult::Image` for images
- Paths go through `EditorContext::ResolveAssetPath()`, which keeps them inside the project's `Assets` directory
- Work on the main thread only - tool handlers already run there
## 3. Test it
In `Tests/Editor/EditorToolsTests.cpp`:
- Add the name to `ToolNames` (the inventory test fails until you do, and the bad-arguments test then calls the tool with junk)
- A test case per tool: success, the result's content, the effect on the editor, undo where it's a command, and every failure an agent can cause
- If the feature changes what an agent's whole workflow looks like, extend `Tests/Editor/McpAgentSmokeTest.py`
## 4. Document it
Add it to the tool table in `docs/AIControl.md#tools`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |