leehack/mcp_dart/mcp-developer

MCP Developer

Use this skill when the work involves MCP protocol behavior, cross-SDK interop, server/client debugging, or host configuration.

Workflow

1. Identify the transport first: stdio, Streamable HTTP, SSE, or a host-specific adapter.
2. Preserve wire-level MCP semantics. Keep JSON-RPC ids, method names, capability flags, metadata, and error codes in their original spec-compatible shape.
3. Check advertised capabilities before calling capability-specific methods.
4. 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

1. 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.
2. 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.
3. If changing this Dart SDK/CLI package itself, also run mcp_dart conformance --suite all --json for the built-in protocol regression fixtures.
4. 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.
5. 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.