
mcp-development
Workflow-first MCP server design with schema-first tools, context-aware outputs, and evaluation discipline.
- version
- 0.6.3
- GitHub stars
- 9
Install
/plugin install mcp-development@agent-powerupsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.
Contents
Discovered from sourceSkills 1
MCP Server Builder
Use this skill when designing or implementing an MCP server.
When to Use
- Building a new MCP server from scratch.
- Refactoring a weak or over-thin MCP tool surface.
- Reviewing whether a server exposes the right workflows.
- Designing evaluation cases for MCP usability.
Core Principles
- Build workflow tools, not thin endpoint wrappers — one tool should complete a meaningful agent task, not expose a single API method.
- Keep input schemas narrow and typed — reject unknown fields; use enums over free strings where possible.
- Return high-signal, size-bounded outputs — default to concise; add
detailorverboseflags when larger payloads are occasionally useful. - Make error messages corrective — tell the agent what to do next, not just what went wrong.
- Prefer human-meaningful identifiers over opaque IDs when both are available.
- Design evaluation cases before declaring the server "done".
Workflow
1. Map the workflow
- Identify the real tasks an agent must complete, not the underlying API surface.
- Merge low-level steps into meaningful operations (e.g., one
create_and_publishtool instead of separatecreate,validate,publish).
2. Design the tool surface
tool name: stable, verb-noun, describes the workflow step
input schema: typed, narrow, required fields only + optional detail flags
output shape: consistent structure across all tools in the server
failure modes: named error codes + correction hint
3. Design for context limits
- Default response fits in ~500 tokens for list operations, ~1500 for detail operations.
- Add
limit,page, orsummaryparameters for large result sets. - Truncate deterministically (e.g., top N by recency) — never truncate randomly.
4. Design corrective errors
Bad error: "Error: 404 Not Found"
Good error: "Resource 'project-123' not found. Use list_projects to see available project IDs."
Every error should tell the agent its next valid action.
5. Implement shared infrastructure first
- Auth handling and token refresh.
- Retry logic with exponential backoff and rate-limit awareness.
- Pagination helpers.
- Output formatting helpers (consistent truncation, redaction of secrets).
6. Evaluate before shipping
- Write representative task scenarios (not unit tests for individual tools).
- Check whether an agent can complete the full workflow using only the exposed tools.
- Redesign weak tools before adding more tools — more tools is not always better.
Server Readiness Checklist
- Every tool completes a meaningful workflow step.
- All inputs are typed and schema-validated.
- Output size is bounded by default.
- All error messages include a correction hint.
- Auth and retry are handled in shared infrastructure.
- At least one end-to-end task scenario has been tested.
- No secrets appear in tool outputs or error messages.
Local References
reference/mcp_best_practices.mdreference/python_mcp_server.mdreference/node_mcp_server.mdreference/evaluation.md
Use the Python and Node references only for the stack you are actually shipping.
Bundled Scripts
scripts/evaluation.py— evaluation scaffoldingscripts/connections.py— connection-oriented examples
Use them as optional helpers, not mandatory runtime requirements.
Sponsors
Details
- Marketplace
- yeaight7/agent-powerups
- Source
- plugins/mcp-development
- Category
- Developer Tools
- License
- Apache-2.0
- Keywords
- mcp, servers, tooling, agent-workflows, schema-first
More from yeaight7/agent-powerups
All 21- memory-optimizationv0.6.3
- quality-gatesv0.6.3
- security-guardrailsv0.6.3
- skill-authoringv0.6.3
- software-engineeringv0.6.3
- spec-driven-developmentv0.6.3
- spec-quality-gatesv0.6.3
- tool-integrationsv0.6.3
- agent-evaluation-labv0.6.3
- agentic-systemsv0.6.3
- codebase-intelligencev0.6.3
- codebase-maintenancev0.6.3
- connected-appsv0.6.3
- context-efficiencyv0.6.3
- data-engineeringv0.6.3
- debugging-diagnosticsv0.6.3
- dev-vitalsv0.6.3
- documentation-systemsv0.6.3
- github-opsv0.6.3
- machine-learning-opsv0.6.3