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-powerups

Run it inside Claude Code after adding the marketplace with /plugin marketplace add yeaight7/agent-powerups.

Contents

Discovered from source

Skills 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 detail or verbose flags 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_publish tool instead of separate create, 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, or summary parameters 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.md
  • reference/python_mcp_server.md
  • reference/node_mcp_server.md
  • reference/evaluation.md

Use the Python and Node references only for the stack you are actually shipping.

Bundled Scripts

  • scripts/evaluation.py — evaluation scaffolding
  • scripts/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