1

testing

Jonathan Miller edited this page 2026-05-20 01:25:22 +00:00

Table of Contents

• Testing
• Build Validation
• Manual Tool Testing
• Via Claude Code
• Via Command Line
• Via curl (Testing the Underlying API)
• Test Checklist
• For Every New Tool
• For Pagination Tools
• For Mutation Tools (Create/Update/Delete)
• Multi-Connection Testing
• Error Case Testing
• Watch Mode Development
• Pre-Release Checklist
• Related

← 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

Scenario	Expected Behavior
API returns 401	Tool returns auth error message
API returns 404	Tool returns "not found" message
API returns 500	Tool returns server error message
API is unreachable	Tool returns connection error
Invalid JSON response	Tool returns parse error
Config file missing	Server fails to start with clear message
Invalid config JSON	Server fails to start with clear message

---

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

Field	Value
Minimum Version	04.07.00
Platform	mcp-server
Applies To	MCP server repositories

Revision	Date	Author	Description
1.0	2026-05-19	Moko Consulting	Initial version