MCP Generator

Auto-generates MCP (Model Context Protocol) tool definitions from OpenAPI 3.1 specifications.

Features

• OpenAPI Scanner: Recursively scans directories for OpenAPI 3.1 specs
• MCP Tool Generator: Converts OpenAPI operations to MCP tool definitions
• Registry Builder: Organizes tools by service with TypeScript/JSON export
• CLI: Production-ready command-line interface
• Type-Safe: Full TypeScript support with generated types

Installation

npm install @bluefly/mcp-generator

CLI Usage

Scan for OpenAPI Specs

mcp-gen scan --path /path/to/project

Generate MCP Tools

# Generate from all specs in directory
mcp-gen generate --path /path/to/project --output ./generated

# Generate for specific service
mcp-gen generate --path /path/to/project --service agent-protocol

# Generate as JSON
mcp-gen generate --path /path/to/project --format json

List Generated Tools

# List all tools
mcp-gen list --path ./generated/registry.json

# Filter by service
mcp-gen list --service agent-protocol

Validate OpenAPI Specs

mcp-gen validate --path /path/to/spec.yaml

Programmatic Usage

Scanner

import { scanOpenAPISpecs } from '@bluefly/mcp-generator';

const result = await scanOpenAPISpecs('/path/to/project', {
  patterns: ['**/*.yaml', '**/*.yml'],
  exclude: ['**/node_modules/**'],
  recursive: true,
});

console.log(`Found ${result.totalSpecs} specs with ${result.totalOperations} operations`);

Generator

import { generateMCPTools } from '@bluefly/mcp-generator';

const tools = await generateMCPTools(spec, {
  outputDir: './generated',
  includeTypes: true,
  includeHandlers: true,
});

console.log(`Generated ${tools.length} tools`);

Registry Builder

import { buildRegistry } from '@bluefly/mcp-generator';

const builder = await buildRegistry(specs, {
  outputDir: './generated',
  format: 'typescript',
});

// Export as TypeScript
await builder.exportTypeScript('./generated/registry.ts');

// Export as JSON
await builder.exportJSON('./generated/registry.json');

// Export individual service modules
await builder.exportServiceModules('./generated/services');

// Get statistics
const stats = builder.getStatistics();
console.log(`Total services: ${stats.totalServices}`);
console.log(`Total tools: ${stats.totalTools}`);

Output Structure

TypeScript Output

generated/
├── registry.ts              # Main registry with all tools
├── types.ts                 # Type definitions
└── services/
    ├── agent-protocol.ts    # Agent protocol tools
    ├── agentic-flows.ts     # Agentic flows tools
    └── ...

JSON Output

generated/
└── registry.json            # Complete registry in JSON format

Generated Tool Structure

Each MCP tool includes:

{
  name: 'service_operationId',
  description: 'Operation summary',
  inputSchema: {
    type: 'object',
    properties: {
      // Path parameters
      // Query parameters
      // Headers
      // Request body
    },
    required: ['param1', 'param2']
  },
  metadata: {
    serviceName: 'service-name',
    operationId: 'operationId',
    method: 'GET',
    path: '/api/resource/{id}',
    tags: ['Resources'],
    authentication: {
      type: 'apiKey',
      location: 'header',
      name: 'X-API-Key'
    },
    sourceSpec: '/path/to/openapi.yaml'
  },
  handler: async (args) => {
    // Generated HTTP request handler
  }
}

Authentication Support

Supports OpenAPI security schemes:

• API Key (header, query, cookie)
• Bearer tokens (JWT)
• Basic auth
• OAuth2

Authentication config is extracted and included in tool metadata.

Examples

Example 1: Generate Tools from Project

# Scan blueflyio projects
mcp-gen scan --path ~/Sites/blueflyio

# Generate all tools
mcp-gen generate \
  --path ~/Sites/blueflyio \
  --output ~/Sites/blueflyio/agent-protocol/generated/mcp-tools

Example 2: Generate for Specific Service

import { scanOpenAPISpecs, generateMCPTools } from '@bluefly/mcp-generator';

// Scan for agent-protocol spec
const result = await scanOpenAPISpecs(
  '~/Sites/blueflyio/agent-protocol'
);

const agentProtocolSpec = result.specs.find(
  s => s.serviceName === 'agent-protocol'
);

// Generate tools
const tools = await generateMCPTools(agentProtocolSpec);

console.log(`Generated ${tools.length} tools for agent-protocol`);

Example 3: Custom Tool Handler

import { MCPToolGenerator } from '@bluefly/mcp-generator';

class CustomGenerator extends MCPToolGenerator {
  // Override handler generation
  protected generateHandler(spec, method, path, operation) {
    return async (args) => {
      // Custom HTTP client implementation
      const response = await fetch(url, {
        method,
        headers: this.buildHeaders(args),
        body: JSON.stringify(args.body),
      });
      return response.json();
    };
  }
}

Testing

# Run tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Lint
npm run lint

# Format
npm run format

Architecture

1. Scanner (src/scanner.ts)

   • Finds OpenAPI specs recursively
   • Parses YAML files
   • Validates OpenAPI structure
   • Extracts service metadata

2. Generator (src/generator.ts)

   • Converts operations to MCP tools
   • Generates input schemas
   • Extracts authentication
   • Creates tool handlers

3. Registry (src/registry.ts)

   • Organizes tools by service
   • Manages tool registry
   • Exports TypeScript/JSON
   • Provides statistics

4. CLI (src/cli.ts)

   • Command-line interface
   • Interactive progress
   • Error handling
   • Output formatting

License

MIT

Author

BlueFly.io