MCP Server Integration

Relevant source files

• README.md
• README_EN.md
• docker-compose.yml
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• package.json
• packages/core/package.json
• packages/core/src/services/model/defaults.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/desktop/package.json
• packages/extension/package.json
• packages/extension/public/manifest.json
• packages/mcp-server/package.json
• packages/mcp-server/src/config/models.ts
• packages/ui/package.json
• packages/web/package.json
• pnpm-lock.yaml
• vercel.json

This document describes the Model Context Protocol (MCP) server implementation in the Prompt Optimizer system. The MCP server exposes prompt optimization capabilities as standardized tools that can be consumed by MCP-compatible AI applications such as Claude Desktop. It runs as a standalone Node.js HTTP service, either independently or integrated with the Docker deployment alongside the web application.

For general deployment instructions, see Deployment and Configuration. For Docker-specific setup, see Docker Deployment. For environment variable configuration, see Environment Configuration and API Keys.

---

Architecture Overview

MCP Server Position in System

MCP Server Deployment Architecture

Sources: packages/mcp-server/package.json1-53 README.md182-246 docker-compose.yml1-44

The MCP server operates as an independent service that bridges external MCP clients with the core prompt optimization engine. It accepts MCP protocol requests over HTTP with Server-Sent Events (SSE) transport, processes them using core services, and returns standardized MCP responses.

---

Package Structure and Dependencies

The MCP server is implemented as the @prompt-optimizer/mcp-server package within the monorepo. Key characteristics:

Attribute	Value
Package name	@prompt-optimizer/mcp-server
Main entry	dist/index.js
Binary entry	dist/start.cjs
Primary dependency	@prompt-optimizer/core (workspace)
MCP SDK	@modelcontextprotocol/sdk v1.24.3
HTTP server	express v4.21.2
Minimum Node.js	18.0.0

Sources: packages/mcp-server/package.json1-53

Key Scripts:

• pnpm mcp:build - Build the MCP server
• pnpm mcp:dev - Run in development mode with hot reload
• pnpm mcp:start - Run in production mode
• pnpm mcp:test - Execute unit tests

Sources: package.json50-53

---

Server Implementation

Entry Point and Server Initialization

Server Startup Sequence

Sources: packages/mcp-server/package.json12-14 env.local.example72-91

The server initialization follows this pattern:

1. Environment Loading: The preload-env.js script loads environment variables from .env.local before application code runs
2. Service Initialization: Core services (ModelManager, PromptService, LLMService, TemplateManager) are instantiated
3. Model Configuration: The setupDefaultModel() function selects an enabled model based on MCP_DEFAULT_MODEL_PROVIDER
4. HTTP Server Setup: Express server mounts the MCP transport handler at /mcp
5. Port Binding: Server listens on MCP_HTTP_PORT (default 3000)

Sources: packages/mcp-server/src/config/models.ts1-69 env.local.example75-80

Model Selection Logic

The MCP server reuses the core package's model management system. The setupDefaultModel() function implements a priority-based model selection:

Model Selection Algorithm

Sources: packages/mcp-server/src/config/models.ts12-66

The function prioritizes:

1. Explicit preference: If MCP_DEFAULT_MODEL_PROVIDER is set, attempts to match by:
   • Direct model key (e.g., "custom_qwen3")
   • Provider ID from providerMeta.id
   • Fuzzy name matching
2. First available: Falls back to the first enabled model from defaultModels
3. Dynamic models: Supports multi-custom models via custom_<suffix> pattern

The selected model is registered in ModelManager with the key "mcp-default".

Sources: packages/mcp-server/src/config/models.ts28-55 packages/core/src/services/model/defaults.ts99-115

---

MCP Tools

The MCP server exposes three tools that wrap core prompt optimization functionality:

Tool Definitions

Tool Name	Purpose	Input Schema	Core Service
optimize-user-prompt	Optimize user-facing prompts	original_prompt, task_description?, language?	PromptService.optimizePrompt()
optimize-system-prompt	Optimize system-level prompts	original_prompt, task_description?, language?	PromptService.optimizePrompt()
iterate-prompt	Iteratively refine existing prompts	current_prompt, iteration_direction, language?	PromptService.iteratePrompt()

Sources: docs/user/mcp-server.md5-14 README.md240-246

Tool Execution Flow

MCP Tool Execution Sequence

Sources: packages/mcp-server/src/config/models.ts1-69

Each tool handler:

1. Validates input parameters against JSON schema
2. Determines language preference (from parameter or MCP_DEFAULT_LANGUAGE)
3. Selects appropriate optimization template (user vs system)
4. Delegates to PromptService for core optimization logic
5. Streams results back to client via MCP protocol

---

Transport Mechanisms

HTTP Transport with SSE

The MCP server uses Server-Sent Events (SSE) over HTTP for bidirectional streaming communication:

HTTP/SSE Transport Flow

Sources: packages/mcp-server/package.json14 docker-compose.yml10-17

HTTP Endpoint Configuration:

• Development: http://localhost:3000/mcp
• Docker deployment: http://localhost:8081/mcp (Nginx proxy)
• Transport type: Streamable HTTP (SSE-based)

The Express server configuration:

• Endpoint: /mcp
• Method: POST (for tool calls)
• Response: text/event-stream for streaming results
• CORS: Configured to allow external clients

Sources: docker-compose.yml11-13 docs/user/mcp-server.md28-32

Docker Nginx Integration

In Docker deployment, Nginx proxies MCP traffic to the internal Node.js server:

Browser/Client → Nginx:80 → /mcp path → Node.js:3000 → MCP Server
                     ↓
                  /  path → Web static files

The Nginx configuration includes:

• Path routing: /mcp forwards to http://localhost:3000/mcp
• Authentication bypass: auth_basic off; for /mcp route (MCP protocol doesn't support Basic Auth)
• WebSocket upgrade: Support for SSE streaming
• CORS headers: Allow cross-origin MCP client connections

Sources: docker-compose.yml10-17 docs/user/mcp-server.md169-183

---

Environment Configuration

Core Environment Variables

The MCP server requires API keys for at least one LLM provider:

Variable Pattern	Description	Example
VITE_OPENAI_API_KEY	OpenAI API key	sk-proj-...
VITE_GEMINI_API_KEY	Google Gemini API key	AIza...
VITE_DEEPSEEK_API_KEY	DeepSeek API key	sk-...
VITE_ZHIPU_API_KEY	Zhipu AI API key	...
VITE_CUSTOM_API_KEY_<suffix>	Multi-custom model key	ollama-key
VITE_CUSTOM_API_BASE_URL_<suffix>	Custom API endpoint	http://localhost:11434/v1
VITE_CUSTOM_API_MODEL_<suffix>	Custom model ID	qwen2.5:7b

Sources: env.local.example4-76

MCP-Specific Configuration

Variable	Default	Options	Purpose
MCP_DEFAULT_MODEL_PROVIDER	(first enabled)	openai, gemini, anthropic, deepseek, siliconflow, zhipu, dashscope, openrouter, modelscope, custom, custom_<suffix>	Select preferred model when multiple are configured
MCP_HTTP_PORT	3000	Any valid port	HTTP server port (Docker ignores this)
MCP_LOG_LEVEL	debug	debug, info, warn, error	Logging verbosity
MCP_DEFAULT_LANGUAGE	zh	zh, en	Default language for prompts

Sources: env.local.example75-90 docker-compose.yml32-35

Docker Deployment Notes:

• In Docker, MCP_HTTP_PORT is fixed at 3000 internally
• External access is through Nginx on NGINX_PORT (default 80)
• The /mcp path is automatically routed to the MCP server

Sources: docker-compose.yml10-17 docker-compose.yml32

---

Client Integration

Claude Desktop Configuration

Claude Desktop requires a services.json configuration file to connect to the MCP server:

Configuration File Locations:

• Windows: %APPDATA%\Claude\services
• macOS: ~/Library/Application Support/Claude/services
• Linux: ~/.config/Claude/services

Example services.json:

Sources: docs/user/mcp-server.md93-116 README.md219-238

Connection Validation Flow

Claude Desktop Connection Flow

Sources: docs/user/mcp-server.md93-116

The connection process:

1. Claude Desktop reads services.json on startup
2. Attempts HTTP connection to each configured MCP server
3. Requests server capabilities via MCP protocol
4. Displays available tools in Claude's UI
5. Routes tool calls through MCP transport when user invokes them

---

Testing and Validation

MCP Inspector Integration

The official MCP Inspector tool can test the server:

Inspector Configuration:

1. Open Inspector web UI (typically http://localhost:5173)
2. Select transport: Streamable HTTP
3. Server URL: http://localhost:3000/mcp (or http://localhost:8081/mcp for Docker)
4. Click "Connect"
5. Test each tool with sample inputs

Sources: docs/user/mcp-server.md119-135

Common Connection Issues

Issue	Cause	Solution
Port occupied	Another service on port 3000	Change MCP_HTTP_PORT or stop conflicting service
No enabled models	Missing or invalid API keys	Configure at least one valid API key
Provider mismatch	Wrong MCP_DEFAULT_MODEL_PROVIDER	Verify provider name matches configured keys
401 Authentication error (Docker)	Nginx Basic Auth on /mcp	Fixed in v1.4.0+; older versions must disable ACCESS_PASSWORD

Sources: docs/user/mcp-server.md137-193 docs/user/mcp-server_en.md149-210

---

Development vs Production Deployment

Development Mode

Development mode features:

• Hot reload on code changes
• Debug logging enabled by default
• Standalone execution (no web app)

Sources: docs/user/mcp-server.md34-53 packages/mcp-server/package.json13

Docker Production Deployment

Production deployment characteristics:

• Unified container with web app and MCP server
• Nginx reverse proxy for routing
• Optional Basic Auth for web app (bypassed for /mcp)
• Health checks for both services
• Persistent configuration via environment variables

Sources: docker-compose.yml1-44 README.md112-127 docs/user/mcp-server.md13-32

Docker Compose Configuration

The docker-compose.yml defines the integrated deployment:

Sources: docker-compose.yml1-44

The health check validates both:

• Web application: http://localhost:80/
• MCP server: http://localhost:80/mcp

This ensures the entire stack is operational before marking the container as healthy.

---

Integration with Core Services

Service Dependencies

MCP Server Service Dependencies

Sources: packages/mcp-server/src/config/models.ts1-69

The MCP server operates entirely through core service APIs:

1. Model Management: Uses ModelManager to store and retrieve the selected model configuration
2. Prompt Optimization: Delegates to PromptService.optimizePrompt() for both user and system prompts
3. Iteration: Calls PromptService.iteratePrompt() for refinement workflows
4. Template Selection: TemplateManager provides optimization templates based on prompt type and language
5. LLM Interaction: LLMService handles streaming API calls through provider adapters
6. Persistence: FileStorageProvider stores model configurations in Node.js filesystem

This architecture ensures the MCP server has zero business logic duplication—it purely provides a protocol adapter layer over existing core functionality.

Sources: packages/mcp-server/src/config/models.ts6-69 packages/core/src/services/model/defaults.ts1-119