Skip to main content
mcp-development Build production-grade MCP (Model Context Protocol) servers with observability, correlation ID tracing, and dual logging. Use when creating new MCP servers, adding tools to existing servers, implementing file logging, debugging MCP issues, wrapping CLI tools with spawnSyncCollect, or following Side Quest marketplace patterns. Covers @side-quest/core/mcp declarative API, @side-quest/core/spawn CLI wrapper patterns, Zod schemas, Bun runtime, and 9 gold standard patterns validated across Kit plugin (18 tools). Includes error handling, response format switching, MCP annotations, and graceful degradation.
Zur Installation springen Skills Marktplatz Entdecken und erkunden Sie KI-Skills, die von der Community erstellt wurden.
Verwandte Berufe SOC
Basierend auf der SOC-Berufsklassifikation
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Prompt-Details anzeigen Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
npx skills add https://github.com/nathanvale/side-quest-marketplace-old --skill mcp-developmentDer Befehl bleibt in einer Zeile. Scrollen Sie horizontal, um ihn vor dem Kopieren vollständig zu prüfen.
Sie bevorzugen eine lokale Kopie? Laden Sie die Dateien herunter, die SkillsMP derzeit vorliegen.
ZIP herunterladen Herunterladen... Mehr aus diesem Repository Web scraping, site crawling, search, structured data extraction, and AI-powered research with Firecrawl CLI. Use when you need full page content as markdown, JS-rendered pages, anti-bot bypass, crawling entire documentation sites, extracting structured data with schemas, or deep web research. Prefer WebFetch for quick questions about a known URL. Prefer WebSearch for finding links without full content.
Unified inbox processor - handles ALL content types (clippings, transcriptions, VTT files, attachments) with parallel subagents and single-table review. Routes to appropriate creator based on proposed_template.
Build production-grade CLI tools with Bun. Reference implementation covering argument parsing patterns (--flag value, --flag=value, --flag), dual markdown/JSON output, error handling, subcommands, and testing. Use when building CLIs, designing argument parsing, implementing command structures, reviewing CLI quality, or learning Bun CLI best practices.
name mcp-development description Build production-grade MCP (Model Context Protocol) servers with observability, correlation ID tracing, and dual logging. Use when creating new MCP servers, adding tools to existing servers, implementing file logging, debugging MCP issues, wrapping CLI tools with spawnSyncCollect, or following Side Quest marketplace patterns. Covers @side-quest/core/mcp declarative API, @side-quest/core/spawn CLI wrapper patterns, Zod schemas, Bun runtime, and 9 gold standard patterns validated across Kit plugin (18 tools). Includes error handling, response format switching, MCP annotations, and graceful degradation.
MCP Development Skill
Build production-grade MCP servers using @side-quest/core/mcp and Bun.
Quick Start
/plugin-template:create my-plugin
cd plugins/my-plugin
Create mcp/index.ts:
#!/usr/bin/env bun
import { createCorrelationId, log, startServer, tool, z } from "@side-quest/core/mcp" ;
tool ("hello" , {
description : "A simple greeting tool" ,
inputSchema : {
name : z.string ().describe ("Name to greet" ),
response_format : z.enum (["markdown" , "json" ]).optional ()
.describe
"Output format: 'markdown' (default) or 'json'"
annotations
readOnlyHint
true
destructiveHint
false
idempotentHint
true
openWorldHint
false
async
args
Record
string
unknown
const
as
name
string
response_format
string
const
createCorrelationId
info
tool
"hello"
args
"greeting"
const
`Hello, ${name} !`
const
"json"
JSON
stringify
`# Hello\n\n${greeting} `
info
tool
"hello"
success
true
"greeting"
return
content
type
"text"
as
const
startServer
"my-plugin"
version
"1.0.0"
fileLogging
enabled
true
subsystems
"greeting"
level
"debug"
{
"mcpServers" : {
"my-plugin" : {
"command" : "bun" ,
"args" : [ "run" , "${CLAUDE_PLUGIN_ROOT}/mcp/index.ts" ]
}
}
}
Test: bun run mcp/index.ts
6-Step Handler Pattern Every handler follows this pattern:
async (args : Record <string , unknown >) => {
const { query, response_format } = args as { query : string ; response_format ?: string };
const cid = createCorrelationId ();
const startTime = Date .now ();
log.info ({ cid, tool : "my_tool" , args : { query } }, "search" );
try {
const result = await doSomething (query);
const text = response_format === "json" ? JSON .stringify (result) : formatAsMarkdown (result);
log.info ({ cid, tool : "my_tool" , success : true , durationMs : Date .now () - startTime }, "search" );
return { content : [{ type : "text" as const , text }] };
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String (error);
log.error ({ cid, tool : "my_tool" , error : errorMessage }, "search" );
return {
content : [{ type : "text" as const , text : JSON .stringify ({ error : errorMessage, hint : "Recovery action" , isError : true }) }],
isError : true
};
}
}
Gold Standard Patterns 9 production-validated patterns from Kit plugin. See @./references/gold-standard-patterns.md for details.
# Pattern Purpose 1 Declarative Tool Registration Type-safe Zod schemas + MCP annotations 2 Correlation ID Tracing Request tracking across logs 3 Structured Error Responses { error, hint, isError: true }4 Response Format Switching Markdown (default) + JSON 5 File Logging Configuration Subsystem-based hierarchical logs 6 MCP Annotations readOnlyHint, destructiveHint, etc.7 No Nested Package.json Avoid MCP discovery failures 8 Dual Logging MCP protocol + file persistence 9 Separation of Concerns Business logic vs MCP layer
Tool Registration tool ("my_tool" , {
description : "What this tool does" ,
inputSchema : {
query : z.string ().describe ("Search query" ),
limit : z.number ().optional ().describe ("Max results" ),
response_format : z.enum (["markdown" , "json" ]).optional ()
.describe ("Output format: 'markdown' (default) or 'json'" ),
},
annotations : {
readOnlyHint : true ,
destructiveHint : false ,
idempotentHint : true ,
openWorldHint : false ,
},
}, handler);
File Logging startServer ("my-plugin" , {
version : "1.0.0" ,
fileLogging : {
enabled : true ,
subsystems : ["search" , "index" , "api" ],
level : "debug" ,
maxSize : 10_000_000 ,
maxFiles : 5 ,
},
});
Logs: ~/.claude/logs/<plugin>.jsonl
View: tail -f ~/.claude/logs/my-plugin.jsonl | jq
Filter: jq 'select(.cid == "abc123")'
CLI Wrapper Pattern For tools wrapping external CLIs:
import { buildEnhancedPath, spawnSyncCollect } from "@side-quest/core/spawn" ;
const result = spawnSyncCollect (
["bun" , "run" , `${pluginRoot} /src/cli.ts` , "search" , query],
{ env : { PATH : buildEnhancedPath () } }
);
return {
...(result.exitCode !== 0 ? { isError : true } : {}),
content : [{ type : "text" as const , text : result.exitCode === 0 ? result.stdout : result.stderr }],
};
Error Handling For detailed error patterns, see @./references/error-handling.md.
enum ToolError {
InvalidInput = "INVALID_INPUT" ,
NotFound = "NOT_FOUND" ,
Timeout = "TIMEOUT" ,
InternalError = "INTERNAL_ERROR" ,
}
return {
content : [{ type : "text" , text : JSON .stringify ({ error : msg, errorType, hint, isError : true }) }],
isError : true
};
type Result <T> = { ok : true ; data : T } | { ok : false ; error : string ; hint ?: string };
const isSuccess = <T>(r : Result <T>): r is { ok : true ; data : T } => r.ok ;
Advanced Features For complete examples, see @./references/core-mcp-api.md.
try {
return await semanticSearch (query);
} catch (error) {
if (error.message .includes ("not available" )) {
log.warning ({ cid, fallback : "grep" }, "search" );
return await grepSearch (query);
}
throw error;
}
const withTimeout = <T>(promise : Promise <T>, ms : number
Promise .race ([promise, new Promise <T>((_, reject ) => setTimeout (() => reject (new Error ("Timeout" )), ms))]);
enum ResponseFormat { MARKDOWN = "markdown" , JSON = "json" }
const format = response_format === "json" ? ResponseFormat .JSON : ResponseFormat .MARKDOWN ;
Testing import { describe, expect, test } from "bun:test" ;
describe ("my-server" , () => {
test ("executes tool" , async () => {
const result = await callTool ("mcp__my-plugin_my-server__hello" , { name : "Nathan" });
expect (result.content [0 ].text ).toContain ("Hello" );
});
test ("handles errors" , async () => {
const result = await callTool ("mcp__my-plugin_my-server__search" , { query : "" });
expect (result.isError ).toBe (true );
});
});
Troubleshooting Problem Solution Server won't start bun run mcp/index.ts to check errorsTool not appearing Check .mcp.json path, verify tool name pattern Handler crashes Add try/catch, log args before processing Nested package.json Delete it — breaks MCP discovery
Reference Links
@./references/gold-standard-patterns.md — 9 patterns with pitfalls + best practices
@./references/kit-case-study.md — Kit's 18-tool production implementation
@./references/core-mcp-api.md — @side-quest/core/mcp + @side-quest/core/spawn
@./references/error-handling.md — Error taxonomy and recovery strategies
@./references/mcp-protocol.md — MCP protocol and marketplace conventions
/plugin-template:create — Generate plugin scaffold/review-mcp — Validate against checklist
Summary
Import: tool, startServer, log, createCorrelationId, z from @side-quest/core/mcpRegister: Tools with Zod schemas and annotationsLog: With subsystems — log.info(data, "subsystem")Trace: Correlation IDs on every log entryFormat: Support markdown (default) + JSONErrors: Return { error, hint, isError: true }Files: Logs to ~/.claude/logs/<plugin>.jsonl Production example: @../../kit/CLAUDE.md
