@stackkedjohn/mcp-factory-cli 0.1.0

package/src/parsers/openapi.ts

@@ -0,0 +1,238 @@
+import { APISchema, Endpoint, Parameter, SchemaType, AuthConfig, RequestBody, ResponseSchema, ErrorSchema } from '../schema/api-schema.js';
+
+/**
+ * Parse OpenAPI 3.x or Swagger 2.0 specification into unified APISchema
+ */
+export function parseOpenAPI(spec: any): APISchema {
+  const isSwagger2 = spec.swagger === '2.0';
+  const isOpenAPI3 = spec.openapi?.startsWith('3.');
+
+  if (!isSwagger2 && !isOpenAPI3) {
+    throw new Error('Unsupported spec version. Only OpenAPI 3.x and Swagger 2.0 are supported.');
+  }
+
+  return {
+    name: spec.info.title || 'API',
+    baseUrl: getBaseUrl(spec),
+    auth: detectAuth(spec),
+    endpoints: parseEndpoints(spec),
+  };
+}
+
+/**
+ * Extract base URL from spec
+ */
+function getBaseUrl(spec: any): string {
+  // OpenAPI 3.x
+  if (spec.servers && spec.servers.length > 0) {
+    return spec.servers[0].url;
+  }
+
+  // Swagger 2.0
+  if (spec.host) {
+    const scheme = spec.schemes?.[0] || 'https';
+    const basePath = spec.basePath || '';
+    return `${scheme}://${spec.host}${basePath}`;
+  }
+
+  return '';
+}
+
+/**
+ * Detect authentication configuration
+ */
+function detectAuth(spec: any): AuthConfig {
+  const securitySchemes = spec.components?.securitySchemes || spec.securityDefinitions || {};
+  const firstScheme = Object.values(securitySchemes)[0] as any;
+
+  if (!firstScheme) {
+    return { type: 'none' };
+  }
+
+  switch (firstScheme.type) {
+    case 'apiKey':
+      return {
+        type: 'api-key',
+        location: firstScheme.in === 'header' ? 'header' : 'query',
+        name: firstScheme.name,
+        description: firstScheme.description,
+      };
+    case 'http':
+      if (firstScheme.scheme === 'bearer') {
+        return { type: 'bearer', description: firstScheme.description };
+      }
+      if (firstScheme.scheme === 'basic') {
+        return { type: 'basic', description: firstScheme.description };
+      }
+      return { type: 'none' };
+    case 'oauth2':
+      return { type: 'oauth', description: firstScheme.description };
+    default:
+      return { type: 'none' };
+  }
+}
+
+/**
+ * Parse all endpoints from spec
+ */
+function parseEndpoints(spec: any): Endpoint[] {
+  const endpoints: Endpoint[] = [];
+  const paths = spec.paths || {};
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const methods = ['get', 'post', 'put', 'patch', 'delete', 'options', 'head'];
+
+    for (const method of methods) {
+      const operation = (pathItem as any)[method];
+      if (operation) {
+        endpoints.push(parseOperation(path, method, operation, pathItem as any));
+      }
+    }
+  }
+
+  return endpoints;
+}
+
+/**
+ * Parse a single operation into an Endpoint
+ */
+function parseOperation(path: string, method: string, operation: any, pathItem: any): Endpoint {
+  const parameters: Parameter[] = [];
+
+  // Parse path-level parameters
+  if (pathItem.parameters) {
+    parameters.push(...parseParameters(pathItem.parameters));
+  }
+
+  // Parse operation-level parameters
+  if (operation.parameters) {
+    parameters.push(...parseParameters(operation.parameters));
+  }
+
+  // Parse request body (OpenAPI 3.x)
+  let requestBody: RequestBody | undefined;
+  if (operation.requestBody) {
+    const content = operation.requestBody.content || {};
+    const jsonContent = content['application/json'];
+    if (jsonContent?.schema) {
+      requestBody = {
+        description: operation.requestBody.description || '',
+        required: operation.requestBody.required || false,
+        contentType: 'application/json',
+        schema: parseSchema(jsonContent.schema),
+      };
+    }
+  }
+
+  // Parse response (use first successful response)
+  const responses = operation.responses || {};
+  const successCode = Object.keys(responses).find(code => code.startsWith('2')) || '200';
+  const successResponse = responses[successCode] || {};
+  const responseContent = successResponse.content?.['application/json'];
+
+  const response: ResponseSchema = {
+    statusCode: parseInt(successCode),
+    description: successResponse.description || '',
+    contentType: 'application/json',
+    schema: responseContent?.schema ? parseSchema(responseContent.schema) : { type: 'object' },
+  };
+
+  // Parse error responses
+  const errors: ErrorSchema[] = [];
+  for (const [code, resp] of Object.entries(responses)) {
+    if (!code.startsWith('2') && code !== 'default') {
+      const errorResp = resp as any;
+      const errorContent = errorResp.content?.['application/json'];
+      errors.push({
+        statusCode: parseInt(code),
+        description: errorResp.description || `Error ${code}`,
+        schema: errorContent?.schema ? parseSchema(errorContent.schema) : undefined,
+      });
+    }
+  }
+
+  return {
+    id: operation.operationId || `${method}_${path.replace(/\//g, '_')}`,
+    method: method.toUpperCase() as 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    path,
+    description: operation.description || operation.summary || '',
+    parameters,
+    requestBody,
+    response,
+    errors,
+  };
+}
+
+/**
+ * Parse parameters array
+ */
+function parseParameters(params: any[]): Parameter[] {
+  return params.map((param) => {
+    // Handle $ref
+    if (param.$ref) {
+      // For simplicity, we'll skip resolving refs
+      return null;
+    }
+
+    // Only parse path, query, and header parameters (not body)
+    if (!['path', 'query', 'header'].includes(param.in)) {
+      return null;
+    }
+
+    const schema = param.schema || { type: param.type };
+
+    return {
+      name: param.name,
+      in: param.in as 'path' | 'query' | 'header',
+      required: param.required || false,
+      description: param.description || '',
+      schema: parseSchema(schema),
+    };
+  }).filter(Boolean) as Parameter[];
+}
+
+/**
+ * Parse JSON Schema into SchemaType
+ */
+function parseSchema(schema: any): SchemaType {
+  if (!schema) {
+    return { type: 'string' };
+  }
+
+  // Handle basic types
+  if (schema.type === 'object' || schema.properties) {
+    const properties: Record<string, SchemaType> = {};
+    const required = schema.required || [];
+
+    for (const [key, value] of Object.entries(schema.properties || {})) {
+      properties[key] = parseSchema(value);
+    }
+
+    return {
+      type: 'object',
+      properties,
+      required,
+    };
+  }
+
+  if (schema.type === 'array') {
+    return {
+      type: 'array',
+      items: parseSchema(schema.items),
+    };
+  }
+
+  // Enum
+  if (schema.enum) {
+    return {
+      type: schema.type || 'string',
+      enum: schema.enum,
+    };
+  }
+
+  // Basic types with format
+  return {
+    type: schema.type || 'string',
+    format: schema.format,
+  };
+}

package/src/parsers/postman.ts

@@ -0,0 +1,6 @@
+import { APISchema } from '../schema/api-schema.js';
+import { ParseError } from '../utils/errors.js';
+
+export function parsePostman(collection: any): APISchema {
+  throw new ParseError('Postman collection parsing not yet implemented');
+}

package/src/registry/manager.ts

@@ -0,0 +1,62 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+
+export interface RegistryEntry {
+  name: string;
+  path: string;
+  createdAt: string;
+}
+
+export interface Registry {
+  servers: RegistryEntry[];
+}
+
+const REGISTRY_DIR = path.join(os.homedir(), '.mcp-factory');
+const REGISTRY_FILE = path.join(REGISTRY_DIR, 'registry.json');
+
+async function ensureRegistry(): Promise<void> {
+  try {
+    await fs.access(REGISTRY_FILE);
+  } catch {
+    await fs.mkdir(REGISTRY_DIR, { recursive: true });
+    await fs.writeFile(REGISTRY_FILE, JSON.stringify({ servers: [] }, null, 2));
+  }
+}
+
+export async function loadRegistry(): Promise<Registry> {
+  await ensureRegistry();
+  const content = await fs.readFile(REGISTRY_FILE, 'utf-8');
+  return JSON.parse(content);
+}
+
+export async function saveRegistry(registry: Registry): Promise<void> {
+  await ensureRegistry();
+  await fs.writeFile(REGISTRY_FILE, JSON.stringify(registry, null, 2));
+}
+
+export async function addServer(name: string, serverPath: string): Promise<void> {
+  const registry = await loadRegistry();
+
+  // Remove existing entry if present
+  registry.servers = registry.servers.filter(s => s.name !== name);
+
+  // Add new entry
+  registry.servers.push({
+    name,
+    path: path.resolve(serverPath),
+    createdAt: new Date().toISOString(),
+  });
+
+  await saveRegistry(registry);
+}
+
+export async function getServer(name: string): Promise<RegistryEntry | undefined> {
+  const registry = await loadRegistry();
+  return registry.servers.find(s => s.name === name);
+}
+
+export async function listServers(): Promise<RegistryEntry[]> {
+  const registry = await loadRegistry();
+  return registry.servers;
+}

package/src/schema/api-schema.ts

@@ -0,0 +1,87 @@
+export interface APISchema {
+  name: string;
+  baseUrl: string;
+  auth: AuthConfig;
+  endpoints: Endpoint[];
+  commonHeaders?: Record<string, string>;
+  rateLimit?: RateLimitConfig;
+  pagination?: PaginationConfig;
+}
+
+export interface AuthConfig {
+  type: 'api-key' | 'bearer' | 'oauth' | 'basic' | 'none';
+  location?: 'header' | 'query';
+  name?: string;
+  description?: string;
+}
+
+export interface Endpoint {
+  id: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  description: string;
+  parameters: Parameter[];
+  requestBody?: RequestBody;
+  response: ResponseSchema;
+  errors: ErrorSchema[];
+}
+
+export interface Parameter {
+  name: string;
+  in: 'path' | 'query' | 'header';
+  description?: string;
+  required: boolean;
+  schema: SchemaType;
+}
+
+export interface RequestBody {
+  description?: string;
+  required: boolean;
+  contentType: string;
+  schema: SchemaType;
+}
+
+export interface ResponseSchema {
+  statusCode: number;
+  description?: string;
+  contentType: string;
+  schema: SchemaType;
+}
+
+export interface ErrorSchema {
+  statusCode: number;
+  description: string;
+  schema?: SchemaType;
+}
+
+export interface SchemaType {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  properties?: Record<string, SchemaType>;
+  items?: SchemaType;
+  required?: string[];
+  enum?: string[];
+  format?: string;
+}
+
+export interface RateLimitConfig {
+  strategy: 'header-based' | 'retry-after' | 'none';
+  headerName?: string;
+  requestsPerWindow?: number;
+  windowSeconds?: number;
+}
+
+export interface PaginationConfig {
+  style: 'cursor' | 'offset' | 'page' | 'link-header';
+  cursorParam?: string;
+  limitParam?: string;
+  offsetParam?: string;
+  pageParam?: string;
+}
+
+export interface DetectedPatterns {
+  authPattern: 'api-key' | 'bearer' | 'oauth' | 'basic' | 'none';
+  paginationStyle?: 'cursor' | 'offset' | 'page' | 'link-header';
+  rateLimitStrategy?: 'header-based' | 'retry-after' | 'none';
+  errorFormat: 'standard' | 'custom';
+  hasWebhooks: boolean;
+}

package/src/utils/errors.ts

@@ -0,0 +1,27 @@
+export class MCPFactoryError extends Error {
+  constructor(message: string, public code: string) {
+    super(message);
+    this.name = 'MCPFactoryError';
+  }
+}
+
+export class ParseError extends MCPFactoryError {
+  constructor(message: string) {
+    super(message, 'PARSE_ERROR');
+    this.name = 'ParseError';
+  }
+}
+
+export class ValidationError extends MCPFactoryError {
+  constructor(message: string) {
+    super(message, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+  }
+}
+
+export class GenerationError extends MCPFactoryError {
+  constructor(message: string) {
+    super(message, 'GENERATION_ERROR');
+    this.name = 'GenerationError';
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,23 @@
+export const logger = {
+  info: (message: string) => {
+    console.log(`ℹ ${message}`);
+  },
+
+  success: (message: string) => {
+    console.log(`✓ ${message}`);
+  },
+
+  error: (message: string) => {
+    console.error(`✗ ${message}`);
+  },
+
+  warn: (message: string) => {
+    console.warn(`⚠ ${message}`);
+  },
+
+  debug: (message: string) => {
+    if (process.env.DEBUG) {
+      console.log(`[DEBUG] ${message}`);
+    }
+  }
+};

package/templates/README.md.hbs

@@ -0,0 +1,40 @@
+# {{name}} MCP Server
+
+MCP server for the {{name}} API.
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "{{name}}": {
+      "command": "node",
+      "args": ["{{absolutePath}}/build/index.js"],
+      "env": {
+        {{#if (eq patterns.authPattern 'api-key')}}
+        "API_KEY": "your-api-key-here"
+        {{/if}}
+        {{#if (eq patterns.authPattern 'bearer')}}
+        "BEARER_TOKEN": "your-bearer-token-here"
+        {{/if}}
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Available tools:
+{{#each endpoints}}
+- `{{id}}`: {{description}}
+{{/each}}

package/templates/client.ts.hbs

@@ -0,0 +1,45 @@
+import fetch from 'node-fetch';
+
+export interface APIClient {
+  baseUrl: string;
+  request: (method: string, path: string, params?: any) => Promise<any>;
+}
+
+export function createClient(baseUrl: string): APIClient {
+  return {
+    baseUrl,
+    async request(method: string, path: string, params?: any) {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
+
+      {{#if (eq patterns.authPattern 'api-key')}}
+      if (process.env.API_KEY) {
+        {{#if (eq auth.location 'header')}}
+        headers['{{auth.name}}'] = process.env.API_KEY;
+        {{/if}}
+      }
+      {{/if}}
+
+      {{#if (eq patterns.authPattern 'bearer')}}
+      if (process.env.BEARER_TOKEN) {
+        headers['Authorization'] = `Bearer ${process.env.BEARER_TOKEN}`;
+      }
+      {{/if}}
+
+      const url = new URL(path, baseUrl);
+
+      const response = await fetch(url.toString(), {
+        method,
+        headers,
+        body: params ? JSON.stringify(params) : undefined,
+      });
+
+      if (!response.ok) {
+        throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+      }
+
+      return response.json();
+    },
+  };
+}

package/templates/index.ts.hbs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createClient } from './client.js';
+import { tools, handleToolCall } from './tools.js';
+
+const server = new Server(
+  {
+    name: '{{name}}-mcp',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+const client = createClient('{{baseUrl}}');
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) =>
+  handleToolCall(request, client)
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/templates/package.json.hbs

@@ -0,0 +1,20 @@
+{
+  "name": "{{name}}-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for {{name}} API",
+  "type": "module",
+  "main": "build/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0",
+    "node-fetch": "^3.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/templates/test.ts.hbs

@@ -0,0 +1 @@
+console.log('Tests not yet implemented');

package/templates/tools.ts.hbs

@@ -0,0 +1,38 @@
+import { CallToolRequest } from '@modelcontextprotocol/sdk/types.js';
+import { APIClient } from './client.js';
+
+export const tools = [
+  {{#each endpoints}}
+  {
+    name: '{{id}}',
+    description: '{{description}}',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        {{#each parameters}}
+        {{name}}: {
+          type: '{{schema.type}}',
+          {{#if description}}description: '{{description}}',{{/if}}
+        },
+        {{/each}}
+      },
+      required: [{{#each parameters}}{{#if required}}'{{name}}',{{/if}}{{/each}}],
+    },
+  },
+  {{/each}}
+];
+
+export async function handleToolCall(request: CallToolRequest, client: APIClient) {
+  const { name, arguments: args } = request.params;
+
+  {{#each endpoints}}
+  if (name === '{{id}}') {
+    const result = await client.request('{{method}}', '{{path}}', args);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+  {{/each}}
+
+  throw new Error(`Unknown tool: ${name}`);
+}

package/templates/tsconfig.json.hbs

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}

package/templates/types.ts.hbs

@@ -0,0 +1 @@
+export {}; // Types generated from API schema

package/templates/validation.ts.hbs

@@ -0,0 +1 @@
+export {}; // Validation schemas