Skip to main content

INTEGRATION_GUIDE

Integration Guide

How to integrate MCP Generator with your projects.

Integration with Agent Protocol MCP Server

Step 1: Generate Tools

# Generate MCP tools for all BlueFly services
cd /Volumes/AgentPlatform/wikis/blueflyio/technical-docs.wiki/tools/mcp-generator

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

Step 2: Import Registry in Agent Protocol

// In agent-protocol/src/mcp-server/server.ts

import { mcpToolRegistry } from '../generated/mcp-tools/registry';

export function setupMCPServer() {
  const server = new MCPServer();

  // Register all generated tools
  for (const [serviceName, service] of Object.entries(mcpToolRegistry.services)) {
    console.log(`Registering ${service.tools.length} tools for ${serviceName}`);
    
    for (const tool of service.tools) {
      server.registerTool({
        name: tool.name,
        description: tool.description,
        inputSchema: tool.inputSchema,
        handler: tool.handler,
      });
    }
  }

  return server;
}

Step 3: Use Service-Specific Tools

// Import specific service tools
import { agentProtocolTools } from '../generated/mcp-tools/services/agent-protocol';

// Use individual tools
const result = await agentProtocolTools.agent_protocol_getHealth.handler({});

Integration with Claude Desktop

Step 1: Configure MCP Server

// ~/.claude/mcp_servers.json
{
  "agent-protocol": {
    "command": "node",
    "args": [
      "/path/to/agent-protocol/dist/mcp-server.js"
    ],
    "env": {
      "AGENT_PROTOCOL_URL": "http://localhost:3001",
      "API_KEY": "your-api-key"
    }
  }
}

Step 2: Server Implementation

// agent-protocol/src/mcp-server.ts

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { mcpToolRegistry } from './generated/mcp-tools/registry';

const server = new Server(
  {
    name: 'agent-protocol-mcp',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Register all tools
for (const service of Object.values(mcpToolRegistry.services)) {
  for (const tool of service.tools) {
    server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [{
          name: tool.name,
          description: tool.description,
          inputSchema: tool.inputSchema,
        }],
      };
    });

    server.setRequestHandler(CallToolRequestSchema, async (request) => {
      if (request.params.name === tool.name) {
        const result = await tool.handler(request.params.arguments);
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result, null, 2),
            },
          ],
        };
      }
    });
  }
}

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Integration with Existing APIs

Wrap Existing HTTP Client

import { MCPToolGenerator } from '@bluefly/mcp-generator';
import type { ParsedOpenAPISpec } from '@bluefly/mcp-generator';
import { yourHttpClient } from './http-client';

class APIClientGenerator extends MCPToolGenerator {
  protected generateHandler(
    spec: ParsedOpenAPISpec,
    method: string,
    path: string,
    operation: Record<string, unknown>
  ) {
    return async (args: unknown) => {
      // Use your existing HTTP client
      return yourHttpClient.request({
        method,
        url: spec.spec.servers[0].url + path,
        params: args,
      });
    };
  }
}

Integration with Agent Orchestration

Register Tools with Orchestrator

import { mcpToolRegistry } from './generated/mcp-tools/registry';
import { AgentOrchestrator } from '@bluefly/agent-orchestrator';

const orchestrator = new AgentOrchestrator();

// Register all tools as agent capabilities
for (const service of Object.values(mcpToolRegistry.services)) {
  orchestrator.registerCapability({
    name: service.serviceName,
    tools: service.tools.map(tool => ({
      name: tool.name,
      description: tool.description,
      execute: tool.handler,
    })),
  });
}

Integration with GitLab CI/CD

Regenerate Tools on Spec Changes

# .gitlab-ci.yml

regenerate-mcp-tools:
  stage: build
  script:
    - cd tools/mcp-generator
    - npm install
    - npm run generate -- \
        --path ../../ \
        --output ../../agent-protocol/generated/mcp-tools
  artifacts:
    paths:
      - agent-protocol/generated/mcp-tools/
  only:
    changes:
      - "**/openapi.yaml"
      - "**/openapi.yml"

Integration with Development Workflow

Watch Mode for Development

// watch-specs.ts

import { watch } from 'fs';
import { scanOpenAPISpecs, buildRegistry } from '@bluefly/mcp-generator';

const projectPath = process.cwd();

watch(projectPath, { recursive: true }, async (event, filename) => {
  if (filename.endsWith('.yaml') || filename.endsWith('.yml')) {
    console.log(`Detected change in ${filename}, regenerating...`);
    
    const result = await scanOpenAPISpecs(projectPath);
    const builder = await buildRegistry(result.specs, {
      outputDir: './generated/mcp-tools',
    });
    
    await builder.exportTypeScript('./generated/mcp-tools/registry.ts');
    console.log('✓ Tools regenerated');
  }
});

Integration with Testing

Test Generated Tools

import { mcpToolRegistry } from './generated/mcp-tools/registry';

describe('Generated MCP Tools', () => {
  it('should have all expected services', () => {
    expect(mcpToolRegistry.services).toHaveProperty('agent-protocol');
    expect(mcpToolRegistry.services).toHaveProperty('agentic-flows');
  });

  it('should generate valid input schemas', () => {
    for (const service of Object.values(mcpToolRegistry.services)) {
      for (const tool of service.tools) {
        expect(tool.inputSchema).toHaveProperty('type', 'object');
        expect(tool.inputSchema).toHaveProperty('properties');
      }
    }
  });

  it('should have working handlers', async () => {
    const tool = mcpToolRegistry.services['agent-protocol'].tools[0];
    await expect(tool.handler({})).resolves.toBeDefined();
  });
});

Environment Configuration

API Keys and Authentication

# .env

# Service API Keys
AGENT_PROTOCOL_API_KEY=your-key
AGENTIC_FLOWS_API_KEY=your-key

# Service URLs (override OpenAPI servers)
AGENT_PROTOCOL_URL=http://localhost:3001
AGENTIC_FLOWS_URL=http://localhost:3000

Handler Configuration

import { mcpToolRegistry } from './generated/mcp-tools/registry';

// Configure handlers with environment variables
for (const service of Object.values(mcpToolRegistry.services)) {
  const apiKey = process.env[`${service.serviceName.toUpperCase()}_API_KEY`];
  const baseUrl = process.env[`${service.serviceName.toUpperCase()}_URL`] || service.baseUrl;
  
  // Override handlers with configured values
  for (const tool of service.tools) {
    const originalHandler = tool.handler;
    tool.handler = async (args) => {
      // Inject API key and URL
      return originalHandler({
        ...args,
        apiKey,
        baseUrl,
      });
    };
  }
}

Production Deployment

Build and Package

# Build generator
npm run build

# Generate production tools
npm run generate -- \
  --path ~/Sites/blueflyio \
  --output ~/Sites/blueflyio/agent-protocol/generated/mcp-tools \
  --format typescript

# Build agent-protocol with generated tools
cd ~/Sites/blueflyio/agent-protocol
npm run build

# Package for deployment
npm pack

Docker Integration

# Dockerfile

FROM node:18-alpine

WORKDIR /app

# Copy generated tools
COPY agent-protocol/generated/mcp-tools ./generated/mcp-tools

# Copy application
COPY agent-protocol/dist ./dist
COPY agent-protocol/package.json ./

# Install dependencies
RUN npm install --production

# Start MCP server
CMD ["node", "dist/mcp-server.js"]

Monitoring and Observability

Track Tool Usage

import { mcpToolRegistry } from './generated/mcp-tools/registry';

// Wrap handlers with monitoring
for (const service of Object.values(mcpToolRegistry.services)) {
  for (const tool of service.tools) {
    const originalHandler = tool.handler;
    
    tool.handler = async (args) => {
      const startTime = Date.now();
      
      try {
        const result = await originalHandler(args);
        const duration = Date.now() - startTime;
        
        // Log successful execution
        console.log({
          tool: tool.name,
          service: service.serviceName,
          duration,
          status: 'success',
        });
        
        return result;
      } catch (error) {
        const duration = Date.now() - startTime;
        
        // Log errors
        console.error({
          tool: tool.name,
          service: service.serviceName,
          duration,
          status: 'error',
          error: error.message,
        });
        
        throw error;
      }
    };
  }
}

Best Practices

  1. Regenerate on Spec Changes: Always regenerate when OpenAPI specs change
  2. Version Control: Commit generated tools to version control
  3. Testing: Test generated tools before deployment
  4. Authentication: Use environment variables for API keys
  5. Error Handling: Wrap handlers with proper error handling
  6. Monitoring: Track tool usage and performance
  7. Documentation: Keep OpenAPI specs up to date

Troubleshooting

Tools Not Generating?

  • Check OpenAPI spec validity: npm run validate
  • Verify file paths and permissions
  • Check for YAML syntax errors

Handlers Not Working?

  • Implement custom HTTP client
  • Check authentication configuration
  • Verify API endpoints are accessible

Type Errors?

  • Rebuild: npm run build
  • Check TypeScript version compatibility
  • Verify generated types match specs

Support

For issues and questions:

  • Check documentation in /docs
  • Review examples in /examples
  • Open issue on GitLab

Next Steps: Generate tools for your project and integrate with agent-protocol!