# MCP Factory Tools

Toolchain for building, testing, validating, and shipping MCP servers at scale.

## What's Installed

### Testing & Validation
| Tool | Type | Purpose |
|------|------|---------|
| **mcp-jest** (global CLI) | npm | Discover tools, generate tests, validate protocol compliance, watch mode |
| **mcp-validator** (Janix-ai) | Python (cloned) | Formal MCP protocol compliance reports (2024-11-05 → 2025-06-18) |
| **MCP Inspector** (official) | Cloned | Visual web UI for interactive server debugging |

### Development
| Tool | Type | Purpose |
|------|------|---------|
| **FastMCP** (npm) | Library | Opinionated TS framework for building new MCP servers fast |
| **mcp-add** (global CLI) | npm | One-liner install for customers to add servers to any MCP client |

## Quick Commands

### Discover all tools across 30 servers
```bash
cd factory-tools && node scripts/discover-all.mjs
```
Generates test configs in `test-configs/` for every server.

### Validate all servers for MCP compliance
```bash
cd factory-tools && node scripts/validate-all.mjs
```
Produces compliance reports in `reports/` (JSON + Markdown).

### Validate a single server
```bash
mcp-jest validate --config test-configs/calendly.json
```

### Discover a single server's tools
```bash
mcp-jest discover --config test-configs/calendly.json
```

### Run tests against a server (requires real API keys)
```bash
# Edit test-configs/calendly.json to add real CALENDLY_API_KEY
mcp-jest --config test-configs/calendly-tests.json
```

### Compliance report via mcp-validator (Python)
```bash
cd mcp-validator && source .venv/bin/activate
python -m mcp_testing.scripts.compliance_report \
  --server-command "node ../mcp-diagrams/mcp-servers/calendly/dist/index.js" \
  --protocol-version 2025-06-18
```

## Directory Structure
```
factory-tools/
├── README.md
├── package.json
├── server-registry.json        # All 30 servers, their env vars
├── scripts/
│   ├── discover-all.mjs        # Batch discovery
│   ├── validate-all.mjs        # Batch validation
│   └── fix-unknown-tool-error.mjs  # Template-level bug fix (already applied)
├── test-configs/               # Generated per-server test configs
│   ├── calendly.json           # Base config (for discover/validate)
│   └── calendly-tests.json     # Full test suite (for testing)
├── reports/                    # Compliance & discovery reports
├── mcp-validator/              # Cloned: Python compliance testing
├── mcp-inspector/              # Cloned: Visual debugging UI
└── node_modules/               # fastmcp, mcp-jest (local)
```

## Server Status (as of 2026-02-04)
- **30 servers**, **243 tools**
- **702 test cases** auto-generated
- **100/100 compliance** (all servers FULL compliant after bug fix)
- Bug fixed: Unknown tool error handling (McpError + ErrorCode.MethodNotFound)

## For New Servers (use FastMCP)
```typescript
import { FastMCP } from "fastmcp";
import { z } from "zod";

const server = new FastMCP({ name: "My Server", version: "1.0.0" });

server.addTool({
  name: "my_tool",
  description: "Does a thing",
  parameters: z.object({ input: z.string() }),
  execute: async (args) => String(result),
});

server.start({ transportType: "stdio" });
```

## For Customer Install Docs
```bash
npx mcp-add --name calendly --type local \
  --command "npx mcp-server-calendly" \
  --scope global --clients "claude,cursor,vscode"
```