charlieviettq MCP builder
Design principles
- One capability per tool — clear name, single purpose.
- Strict schemas — JSON Schema for inputs; document required vs optional.
- Predictable errors — machine-readable codes + human message; no stack traces to client by default.
- Idempotent reads — writes clearly labeled; confirm destructive ops in description.
Server checklist
-
serveridentity and version documented - Tool list small and discoverable
- Input validation before side effects
- Timeouts and size limits on responses
- Auth documented (env vars, OAuth, local only)
- README: install, config, example tool calls
Tool definition pattern
{
"name": "search_docs",
"description": "Search internal docs by query. Read-only.",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "Search terms" },
"limit": { "type": "integer", "minimum": 1, "maximum": 50 }
},
"required": ["query"]
}
}
Testing
- Unit test handlers with fixture inputs.
- Integration test with MCP client or inspector.
- Verify error paths (invalid args, upstream failure).
Security
- No broad filesystem or shell unless required and scoped.
- Sanitize paths; block path traversal.
- Do not return secrets in tool results.
Related
Use agent-tool-contracts for cross-platform tool design beyond MCP.