mcp-development

Import tool, startServer, log, createCorrelationId, and z from @side-quest/core/mcp, register tools with Zod input schemas and annotations, then call startServer with a version and fileLogging config. Add a .mcp.json pointing to bun run mcp/index.ts and test with bun run mcp/index.ts.

Use spawnSyncCollect and buildEnhancedPath from @side-quest/core/spawn to execute the CLI and capture stdout/stderr. Return stdout on exit code 0, otherwise return stderr with isError set to true, logging the duration with a correlation ID.

The most common cause is a nested package.json inside the mcp directory, which breaks MCP server discovery. Also verify the .mcp.json path uses ${CLAUDE_PLUGIN_ROOT}, the tool name follows conventions, and the server starts without errors via bun run mcp/index.ts.

Enable fileLogging in startServer with named subsystems, then logs are written to ~/.claude/logs/<plugin>.jsonl. Tail the file with jq and filter by correlation ID using jq 'select(.cid == "abc123")' to trace a single request end to end.

For read-only tools like search or list operations, set readOnlyHint: true, destructiveHint: false, idempotentHint: true, and openWorldHint: false. Destructive tools should set destructiveHint: true and openWorldHint: true so LLMs invoke them appropriately.

Return a content array containing JSON with error, hint, and isError fields, plus a top-level isError: true flag. Include a recovery hint telling the user how to fix the issue, and log the error with a correlation ID before returning.