testing

← Home

Testing

Testing procedures for MCP servers built from the Template-MCP template.

Build Validation

# TypeScript compilation (catches type errors)
npm run build

# ESLint (catches style and logic issues)
npm run lint

Both checks must pass before merging.

Manual Tool Testing

Via Claude Code

The primary way to test MCP tools:

1. Build the server: npm run build
2. Register in .mcp.json:

   {
     "mcpServers": {
       "my-mcp": {
         "type": "stdio",
         "command": "node",
         "args": ["/path/to/dist/index.js"]
       }
     }
   }
   

3. Restart Claude Code
4. Ask Claude to use the tools and verify responses

Via Command Line

Test tools by sending MCP protocol messages via stdin:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

Via curl (Testing the Underlying API)

Test the REST API directly to isolate MCP vs. API issues:

curl -s -H "Authorization: Bearer $API_KEY" \
  "https://api.example.com/resources?limit=5" | jq .

Test Checklist

For Every New Tool

• Tool builds without TypeScript errors
• Tool appears in tools/list response
• Tool description is clear and concise
• All parameters have .describe() text
• Required parameters are correctly marked
• Optional parameters have sensible defaults
• Tool returns data in the expected format
• Error cases return meaningful error messages
• Tool works with default connection
• Tool works with explicit connection parameter

For Pagination Tools

• First page returns results
• Subsequent pages return different results
• Empty pages return empty results (not errors)
• Limit parameter restricts result count

For Mutation Tools (Create/Update/Delete)

• Create returns the created resource
• Update modifies only specified fields
• Delete returns confirmation
• Invalid IDs return appropriate errors
• Missing required fields are rejected by Zod

Multi-Connection Testing

Test tools against different connections to verify:

• Default connection works when connection param is omitted
• Named connections work when specified
• Invalid connection names return a clear error
• list_connections shows all configured connections

Error Case Testing

Watch Mode Development

Use watch mode for rapid iteration:

npm run dev

TypeScript recompiles on file save. Restart the Claude Code MCP connection to pick up changes.

Pre-Release Checklist

Before merging to main:

• npm run build succeeds
• npm run lint passes
• All tools tested via Claude Code
• list_connections tool works
• api_request raw tool works
• Config setup wizard works (npm run setup)
• README documents all tools
• CHANGELOG updated

Related

• Development -- tool implementation patterns
• Contributing -- PR testing requirements
• Troubleshooting -- common issues

Repo: Template-MCP · MokoStandards

Printed from wiki · testing