Quick Start Guide

Get started with MCP Generator in 5 minutes.

Installation

cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/tools/mcp-generator
npm install
npm run build

Quick Test

1. Scan Your Project

npm run scan -- --path ~/Sites/blueflyio/agent-protocol

Expected output:

✔ Found 1 OpenAPI specs with 5 operations

Discovered specifications:
  - agent-protocol (1.0.0)
    /Users/.../agent-protocol/openapi/openapi.yaml

2. Generate MCP Tools

npm run generate -- \
  --path ~/Sites/blueflyio/agent-protocol \
  --output ./generated/test

Expected output:

MCP Tool Generator

✔ Found 1 specs with 5 operations
✔ Generated 5 tools from 1 services
✔ Exported to ./generated/test/

Generation Summary:
  Services: 1
  Total Tools: 5

3. View Generated Files

tree generated/test/

Output:

generated/test/
├── registry.ts
└── services/
    └── agent-protocol.ts

4. Inspect a Tool

cat generated/test/services/agent-protocol.ts

You'll see generated MCP tool definitions:

export const agent-protocol_getHealth: MCPToolDefinition = {
  name: "agent-protocol_getHealth",
  description: "Health check",
  inputSchema: {
    type: "object",
    properties: {}
  },
  metadata: {
    serviceName: "agent-protocol",
    operationId: "getHealth",
    method: "GET",
    path: "/health",
    tags: ["Health"],
    sourceSpec: "/.../openapi.yaml"
  },
  handler: async (args: unknown) => {
    // Handler implementation
  }
};

Use Cases

Generate for All BlueFly Projects

npm run generate -- \
  --path ~/Sites/blueflyio \
  --output ~/Sites/blueflyio/agent-protocol/generated/mcp-tools

This will:

• Scan all projects under ~/Sites/blueflyio
• Find all OpenAPI specs
• Generate MCP tools for each service
• Output to agent-protocol for MCP server use

Generate for Specific Service

npm run generate -- \
  --path ~/Sites/blueflyio \
  --service agentic-flows \
  --output ./generated/agentic-flows

Export as JSON (for runtime use)

npm run generate -- \
  --path ~/Sites/blueflyio/agent-protocol \
  --output ./generated \
  --format json

Integration with Agent Protocol

The generated tools can be used directly in agent-protocol MCP server:

// In agent-protocol MCP server
import { mcpToolRegistry } from './generated/mcp-tools/registry';

// Register all tools
for (const service of Object.values(mcpToolRegistry.services)) {
  for (const tool of service.tools) {
    server.addTool(tool);
  }
}

Next Steps

1. Customize Handlers: See examples/custom-handler.ts
2. Add Authentication: Configure API keys in tool handlers
3. Run Tests: npm test
4. Build Production: npm run build

Troubleshooting

No specs found?

Check your OpenAPI files:

• Must have openapi: 3.1.0 (or 3.0.x)
• Must have paths object
• Must be valid YAML

Generation errors?

Run validation first:

npm run validate -- --path ~/Sites/blueflyio/agent-protocol

Need help?

npm run scan -- --help
npm run generate -- --help