模型上下文协议服务器

API MCP Server - New Generation

A production-grade Model Context Protocol (MCP) server focused on local API service setup, project integration, API testing, external service connectivity, and integration mapping.

Overview

This MCP server enables AI agents to:

• Test API endpoints with support for all HTTP methods
• Manage API project configurations with templates and authentication
• Connect to external services with connection testing and monitoring
• Map data between integrations for transformation workflows
• Generate API services with Express, Fastify, or Hono templates
• Run local API servers with smoke testing and health verification

Architecture

src/
├── server/          # MCP server entry point and bootstrap
├── tools/           # MCP tool implementations
├── prompts/         # MCP prompt definitions
├── resources/       # MCP resource definitions
├── adapters/       # HTTP and OpenAPI adapters
├── templates/       # API project templates
└── core/            # Shared types, config, and utilities

Supported Workflows

1. API Testing

Test individual endpoints or run batch tests:

// Single endpoint test
await test_endpoint({
  url: "https://api.example.com/users",
  method: "GET",
  headers: { "Authorization": "Bearer token" }
});

// Batch testing
await test_batch_endpoints({
  endpoints: [
    { url: "https://api.example.com/health", method: "GET" },
    { url: "https://api.example.com/users", method: "POST", body: { name: "Test" } }
  ]
});

2. Project Integration

Create and manage API project configurations:

// Create from template
await generate_template_project({
  template: "rest-api",
  name: "my-api",
  baseUrl: "http://localhost:3000/api"
});

// Custom configuration
await create_project_config({
  name: "my-api",
  baseUrl: "https://api.example.com",
  auth: { type: "bearer", token: "secret" },
  endpoints: [
    { id: "list", name: "List Users", url: "{{baseUrl}}/users", method: "GET" }
  ]
});

3. External Service Connectivity

Register and monitor external API connections:

await connect_external_service({
  name: "stripe-api",
  type: "payment",
  url: "https://api.stripe.com/v1",
  token: "your_stripe_secret_key_here"
});

await test_connection({ serviceName: "stripe-api" });

4. Integration Mapping

Define field mappings for data transformation:

await create_integration_mapping({
  name: "user-sync",
  sourceService: "internal-api",
  targetService: "crm",
  mappings: [
    { sourcePath: "user.id", targetPath: "externalId" },
    { sourcePath: "user.email", targetPath: "contact.email" }
  ]
});

await apply_mapping({
  mappingName: "user-sync",
  data: { user: { id: "123", email: "test@example.com" } }
});

5. Local API Service Generation

Scaffold a new API service with routes, controllers, services, and middleware:

// Create Express API service
await create_api_service({
  projectPath: "/path/to/project",
  template: "express",
  name: "my-api",
  port: 3000,
  generateOpenApi: true,
  apiVersion: "/api/v1"
});

// Generate environment templates
await generate_env_template({
  projectPath: "/path/to/project",
  serviceName: "my-api",
  port: 3000,
  generateAll: true
});

// Start local API with smoke testing
await run_local_api({
  projectPath: "/path/to/project",
  port: 3000
});

Local Development

Prerequisites

• Node.js 20+
• npm or pnpm

Installation

npm install

Environment Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Development

Run the server in development mode with hot reload:

npm run dev

Building

Compile TypeScript to JavaScript:

npm run build

Type Checking

Run TypeScript type checking without emitting:

npm run typecheck

Linting

Lint the codebase:

npm run lint

Testing

Run All Tests

npm test

Unit Tests

npm run test:unit

Integration Tests

npm run test:integration

Watch Mode

Run tests in watch mode:

npm run test:watch

How AI Agents Should Use This MCP

Tool Discovery

List all available tools:

// Use the MCP's ListTools capability

Using Tools

Each tool accepts JSON arguments and returns structured results:

// Tool response format
{
  content: [
    {
      type: "text",
      text: JSON.stringify(result, null, 2)
    }
  ]
}

Error Handling

Tools return isError: true when operations fail:

if (response.isError) {
  // Handle error
}

Resources

Access project data and documentation via the resources API:

• api://projects - List configured projects
• api://connections - List external connections
• api://mappings - List integration mappings
• api://docs/* - Documentation resources

MCP Protocol

This server implements the Model Context Protocol specification:

• Tools: Executable operations with JSON schemas
• Prompts: Predefined workflow templates
• Resources: URI-addressable data stores

Security Hardening

This release includes the following security improvements:

Path Traversal Protection

• File operations validate that paths remain within the project directory
• Absolute paths and .. traversal are blocked in file generation
• Project path validation ensures the target is a valid directory

Secrets Protection

• Logger automatically redacts sensitive values (passwords, tokens, keys, secrets)
• Config warns on startup when sensitive environment variables are detected
• Generated services include CORS wildcard detection in production mode

Shell Injection Prevention

• Child process spawning uses shell: false to prevent command injection
• Arguments are passed directly, not interpreted through shell

Input Validation

• All project paths are validated before use
• Environment variables are parsed with Zod schema validation
• External service adapters have explicit required/optional env var definitions

Release Summary

Stable Features

Experimental Features

Known Limitations

See docs/known-limitations.md for full list. Key limitations:

• 146 TypeScript errors - Missing npm packages (prisma, @types/*, etc.)
• Integration tests broken - MCP server test setup needs rewrite
• Adapter implementations missing - Only metadata/adapter.ts files exist
• No authentication - API service templates lack auth middleware
• Limited error normalization - Errors not fully standardized across tools

Next Implementation Priorities

1. Install missing packages - Fix TypeScript errors by adding dependencies
2. Rewrite integration tests - MCP server test setup needs redesign
3. Create adapter implementations - Production-grade S3, Stripe, Supabase, etc.
4. Add authentication templates - JWT, session, OAuth2 middleware
5. Verification scripts - Automated setup verification for each adapter
6. Error normalization - Unified error format across all tools

License

MIT