| name | mcp-developer |
| description | Use when building, testing, debugging, or reviewing Model Context Protocol servers, clients, transports, tools, resources, prompts, and agent host configuration. |
MCP Developer
Use this skill when the work involves MCP protocol behavior, cross-SDK interop, server/client debugging, or host configuration.
Workflow
- Identify the transport first: stdio, Streamable HTTP, SSE, or a host-specific adapter.
- Preserve wire-level MCP semantics. Keep JSON-RPC ids, method names, capability flags, metadata, and error codes in their original spec-compatible shape.
- Check advertised capabilities before calling capability-specific methods.
- Reproduce with a protocol-level tool before editing app code:
mcp_dart inspect-server --json -- <server-command> ...- Configure a client/agent host to launch
mcp_dart inspect-client --report /tmp/mcp-client-report.json
- Configure a client/agent host to launch
mcp_dart trace --report /tmp/mcp-trace.json -- <real-server-command> ...
mcp_dart list-tools -- <server-command> ...mcp_dart call-tool <tool> --json-args '{"key":"value"}' -- <server-command> ...mcp_dart inspect --url http://localhost:3000/mcp
- Use
--probe-config with inspect-server when a server needs real tool arguments, resource URIs, prompt arguments, completion values, or task behavior. Keep destructive app actions out of default probes.
- Treat
inspect-server, inspect-client, and trace as the live debugging workflow. They return protocol checks or traffic evidence for real targets; there is no separate live validation command to prefer.
- If changing this Dart SDK/CLI package itself, also run
mcp_dart conformance --suite all --json for the built-in protocol regression fixtures.
- For cross-language issues, test at least one non-Dart peer. Prefer the official TypeScript or Python MCP SDK when a reproduction can be made small, and use published servers such as filesystem/time when the bug depends on real package behavior.
- When changing protocol behavior, add regression coverage for the raw wire shape or interop edge case, not only a convenience API test.
Host Configuration Checks
- Confirm the host launches the exact command and arguments you tested manually.
- Keep secrets in environment variables or host secret stores, not generated config files.
- Avoid printing diagnostic text to stdout for stdio servers; stdout is reserved for JSON-RPC frames.
- Use
inspect-client --report <path> for agent hosts or clients that need a disposable MCP server to connect to.
- Record the MCP protocol version, SDK/package version, and transport in issue notes.
Release And Install Checks
- If the CLI is needed on machines without Dart, use the GitHub release binary.
- Use
mcp_dart update for normal upgrades. For manual installs, rerun the installer command against the same install directory.
- Before recommending a release, verify
dart analyze, focused tests, and any TypeScript/Python interop smoke tests affected by the change.
