MCP Server (Model Context Protocol)

MCP 服务（Model Context Protocol）

一个通用、模块化的服务，用于实现 Model Context Protocol（MCP）。该服务提供了一个框架，可通过标准化 API 控制各种模型并与之交互。

托管部署

可通过 Fronteir AI 使用托管部署。

功能

• 模块化架构，便于扩展
• 动态加载模块
• 核心模型管理功能
• 用于模型上下文的标准化 API
• 简单的配置系统
• 日志记录工具
• 增强的模块结构，实现恰当的关注点分离
• 支持通过 package.json 管理模块依赖
• 配备 Mocha 和 Chai 的全面测试基础设施
• 强大的模块搜索功能
• 在 API 响应中显示模块元数据
• 集成实际的 AI 模型提供商（OpenAI、Stability AI、Anthropic、Hugging Face）
• 支持文本生成、图像生成和语音转文本模型
• 支持兼容模型的流式推理

快速开始

先决条件

• Node.js 18.x 或更高版本
• pnpm 10.x 或更高版本

本项目仅使用 ES Modules（ESM）。所有导入都使用 import 语法，而非 require()。

安装

# Clone the repository
git clone https://github.com/yourusername/mcp-server.git
cd mcp-server

# Install dependencies
pnpm install

运行服务

# Install dependencies
pnpm install

# Start the server
pnpm start

# Start the server in development mode (with auto-reload)
pnpm dev

服务默认将在 http://localhost:3000 启动。

配置

复制示例环境文件，并编辑它以添加 API 密钥：

# Copy the sample environment file
cp sample.env .env

# Edit the file with your favorite editor
nano .env

至少需要添加你打算使用的模型提供商的 API 密钥：

# OpenAI API (for GPT-4 and Whisper)
OPENAI_API_KEY=your_openai_api_key_here

# Stability AI API (for Stable Diffusion)
STABILITY_API_KEY=your_stability_api_key_here

# Anthropic API (for Claude models)
ANTHROPIC_API_KEY=your_anthropic_api_key_here

你可以从以下位置获取这些 API 密钥：

• OpenAI：https://platform.openai.com/api-keys
• Stability AI：https://platform.stability.ai/account/keys
• Anthropic：https://console.anthropic.com/settings/keys

安全

服务器没有全局身份验证层，因此任何能访问该端口的对象都可以调用任意模块路由。对文件系统进行操作或发出出站请求的模块受到以下限制。

模块令牌。 带有副作用的路由接受通过 Authorization: Bearer <token> 或 X-API-Key: <token> 传入的令牌。未设置该变量时，这些路由会保持开放，并在启动时记录警告。

变量	保护的路由
SCANNER_API_TOKEN	/scanner/scan、/scanner/reports/:id/export、/tools/scanner
README_BADGES_API_TOKEN	/readme-badges/update、/readme-badges/detect、/tools/readme-badges

路径限制。 readme-badges 会根据 README_BADGES_ROOT（默认值：工作目录）解析 readmePath 和 rootDir，并拒绝任何超出该目录范围、目标不是 Markdown 文件，或通过符号链接访问目录外内容的请求。scanner 也会以相同方式将导出操作限制在其报告目录内。

出站请求允许列表。 会获取调用方指定 URL 的模块会拒绝环回、链路本地（云元数据）、RFC1918、CGNAT 和其他非公共地址，解析主机名并检查每个返回的地址，同时重新验证每次重定向。对于与某个已知服务通信的模块，其主机也会加入允许列表：

变量	扩展的允许列表范围
CONVERT2DOC_ALLOWED_HOSTS	convert2doc 的 baseUrl（默认值：convert2doc.com）
CRAIGSLIST_ALLOWED_HOSTS	/craigslist/details（默认值：*.craigslist.org）

跨源请求。 CSRF_PROTECTION_ENABLED（默认值 true）会拒绝带有外部 Origin 标头的状态变更请求，防止恶意网页通过绑定到 localhost 的服务器驱动浏览器。未发送 Origin 的客户端（curl、MCP 客户端、服务器到服务器调用）不受影响。请在 CORS_ORIGINS 中列出受信任的浏览器来源。

如果服务器暴露在 localhost 之外，请在具有身份验证功能的反向代理后运行服务器。

测试服务器

此代码库使用 Mocha 和 Chai 进行了全面的测试：

# Run all tests
pnpm test

# Run only module tests
pnpm test:modules

# Run all tests (both core and modules)
pnpm test:all

测试基础设施包括：

1. 针对模块加载、路由和其他核心功能的核心服务器测试
2. 针对每个模块功能的专项测试
3. 在测试中支持 ES 模块
4. 使用 Sinon 的模拟和存根工具

测试以结构化方式组织：

• 核心测试位于 /test/core/
• 模块测试位于各模块的 test/ 目录中

这套全面的测试可确保代码质量，并在进行更改时更轻松地检测回归问题。

提交前钩子

此代码库使用 Husky 和 lint-staged 配置了提交前钩子：

# The hooks are automatically installed when you run
pnpm install

提交前钩子会：

1. 对 JavaScript 文件运行 ESLint
2. 对所有暂存文件运行 Prettier

这样可以确保提交到代码库的所有代码都符合编码标准并保持代码质量。测试套件会持续改进，以提供更好的覆盖率和可靠性；待其更加稳定后，将在提交前钩子中启用。

Docker 支持

此代码库提供 Docker 支持，便于容器化和部署：

# Build and run with Docker
docker build -t mcp-server .
docker run -p 3000:3000 mcp-server

# Or use Docker Compose
docker-compose up

Docker 配置：

• 使用 Node.js 20 Alpine 作为基础镜像
• 暴露端口 3000
• 将 modules 目录挂载为卷，便于管理模块
• 包含运行状况检查

标准 MCP 方法

MCP 服务实现了一组标准方法，所有 MCP 服务都应提供这些方法：

服务器信息

• GET / - 基本服务器信息
• GET /status - 详细服务器状态
• GET /health - 运行状况检查端点
• GET /metrics - 服务器指标

模型管理

• GET /models - 列出可用模型
• GET /model/:modelId - 获取模型信息
• POST /model/:modelId/activate - 激活指定模型
• POST /model/deactivate - 停用当前模型
• GET /model/active - 获取活动模型的信息

推理

• POST /model/infer - 使用活动模型执行推理
• POST /model/:modelId/infer - 使用指定模型执行推理

支持的模型

MCP 服务支持以下模型类型：

模型类型	提供方	能力	示例 ID
GPT 模型	OpenAI	文本生成	gpt-4, gpt-3.5-turbo
Whisper	OpenAI	语音转文本	whisper, whisper-1
Stable Diffusion	Stability AI	图像生成	stable-diffusion-xl-1024-v1-0
Claude 模型	Anthropic	文本生成	claude-3-opus, claude-3-sonnet
自定义模型	Hugging Face	多种	（任意 Hugging Face 模型 ID）

推理示例

使用 GPT-4 生成文本：

# Activate the model
curl -X POST http://localhost:3000/model/gpt-4/activate \
  -H "Content-Type: application/json" \
  -d '{"config": {"temperature": 0.7}}'

# Perform inference
curl -X POST http://localhost:3000/model/infer \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Explain quantum computing in simple terms",
    "temperature": 0.5,
    "max_tokens": 200
  }'

使用 Stable Diffusion 生成图像：

# Activate the model
curl -X POST http://localhost:3000/model/stable-diffusion/activate \
  -H "Content-Type: application/json" \
  -d '{}'

# Generate an image
curl -X POST http://localhost:3000/model/infer \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over mountains",
    "height": 1024,
    "width": 1024,
    "steps": 30
  }'

流式文本生成：

# Enable streaming
curl -X POST http://localhost:3000/model/infer \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a short story about a robot",
    "stream": true
  }'

模块管理

• GET /modules - 列出已安装模块
• GET /modules/:moduleId - 获取模块信息
• GET /modules/search/:query - 按模块 package.json 或元数据中的任意字段搜索模块

工具和资源

• GET /tools - 列出可用工具
• GET /resources - 列出可用资源

有关这些方法的详细信息，请参阅 MCP 标准方法。

配置

配置从环境变量加载，并存储在 src/core/config.js 中。配置服务最简单的方法是编辑项目根目录中的 .env 文件。

环境变量

主要环境变量包括：

变量	描述	默认值
PORT	服务端口	3000
HOST	服务主机	localhost
NODE_ENV	环境（开发/生产）	development
OPENAI_API_KEY	OpenAI API 密钥	（OpenAI 模型必需）
STABILITY_API_KEY	Stability AI API 密钥	（Stable Diffusion 必需）
ANTHROPIC_API_KEY	Anthropic API 密钥	（Claude 模型必需）
HUGGINGFACE_API_KEY	Hugging Face API 密钥	（Hugging Face 模型必需）

有关完整配置选项列表，请参阅 sample.env。

示例

代码库包含多个示例，帮助你快速上手：

• 客户端示例：examples/client.js 演示如何从客户端应用与 MCP 服务交互。
• 自定义模块示例：examples/custom-module/ 展示如何创建一个向服务添加计算器工具的自定义模块。

运行客户端示例：

node examples/client.js

要使用自定义模块示例，请将其复制到 modules 目录：

cp -r examples/custom-module mcp_modules/calculator

创建模块

模块是扩展 MCP 服务的主要方式。每个模块都是一个独立的软件包，可为服务添加新功能。

模块结构

模块现在采用经过增强的结构，组织更加清晰：

mcp_modules/your-module/
├── assets/          # Static assets (images, CSS, etc.)
├── docs/            # Documentation files
├── examples/        # Example usage
├── src/             # Source code
│   ├── controller.js  # HTTP route handlers
│   ├── service.js     # Business logic
│   └── utils.js       # Utility functions
├── test/            # Test files
│   ├── controller.test.js
│   └── service.test.js
├── index.js         # Main module file with register function
├── package.json     # Module metadata, dependencies, and scripts
└── README.md        # Module documentation

每个模块都应包含一个 package.json 文件，其中包括：

• 名称、版本、描述
• 作者和许可证信息
• 依赖项和开发依赖项
• 脚本（尤其是用于测试的脚本）
• 关键词和其他元数据

这种结构能更好地分离关注点、简化测试，并提高模块的可发现性。

模块实现

主模块文件（index.js）必须导出一个 register 函数，该函数会在模块加载时调用：

/**
 * Register this module with the Hono app
 * @param {import('hono').Hono} app - The Hono app instance
 */
export async function register(app) {
  // Register routes, middleware, etc.
  app.get('/your-module/endpoint', c => {
    return c.json({ message: 'Your module is working!' });
  });
}

// Optional: Export module metadata
export const metadata = {
  name: 'Your Module',
  version: '1.0.0',
  description: 'Description of your module',
  author: 'Your Name',
};

示例模块

• mcp_modules/example/ 中提供了一个简单的示例模块，演示如何创建模块。
• examples/custom-module/ 中提供了一个包含计算器工具的复杂示例。
• mcp_modules/health-check/ 中提供了一个用于系统监控的运行状况检查模块。
• mcp_modules/template/ 中提供了用于创建新模块的模板。

创建新模块

你可以使用提供的脚本创建新模块：

# Create a new module
pnpm create-module

# Or with a module name
pnpm create-module my-module

该脚本将：

1. 在 mcp_modules/ 中创建一个新模块目录
2. 复制模板文件
3. 将占位符替换为你的模块信息
4. 提供实现模块的后续步骤

模块搜索

MCP 服务包含强大的搜索功能，可根据模块 package.json 或元数据中的任意信息查找模块。

搜索端点

• GET /modules/search/:query - 搜索任意字段中包含指定查询字符串的模块

搜索示例

# Find modules by name or description
curl http://localhost:3000/modules/search/craigslist

# Find modules by dependency
curl http://localhost:3000/modules/search/jsdom

# Find modules by keyword
curl http://localhost:3000/modules/search/mcp

# Find modules by author
curl http://localhost:3000/modules/search/"MCP Server Team"

# Find modules by license
curl http://localhost:3000/modules/search/ISC

JavaScript 示例

// Function to search modules by any field
async function searchModules(query) {
  const response = await fetch(`http://localhost:3000/modules/search/${query}`);
  const data = await response.json();

  console.log(`Found ${data.count} modules matching "${query}":`);
  data.results.forEach(module => {
    console.log(`- ${module.name} (${module.directoryName}): ${module.description}`);
  });

  return data.results;
}

搜索功能全面，可在任意字段中查找匹配项，包括依赖项、关键词等嵌套对象及其他元数据。

模型提供商

MCP 服务集成了多个 AI 模型提供商：

OpenAI

OpenAI 提供用于文本生成的 GPT 模型，以及用于语音转文本的 Whisper：

// Text generation example
const response = await fetch('http://localhost:3000/model/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Write a poem about artificial intelligence',
    temperature: 0.7,
    max_tokens: 200,
  }),
});

// Speech-to-text example (requires multipart form data)
const formData = new FormData();
formData.append('file', audioFile);
formData.append('model', 'whisper-1');
formData.append('language', 'en');

const response = await fetch('http://localhost:3000/model/whisper/infer', {
  method: 'POST',
  body: formData,
});

Stability AI

Stability AI 提供用于图像生成的 Stable Diffusion：

const response = await fetch('http://localhost:3000/model/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'A photorealistic image of a futuristic city',
    height: 1024,
    width: 1024,
    steps: 30,
    cfg_scale: 7,
  }),
});

// The response includes base64-encoded images
const result = await response.json();
const imageBase64 = result.response[0].base64;

Anthropic

Anthropic 提供用于文本生成的 Claude 模型：

const response = await fetch('http://localhost:3000/model/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Explain how neural networks work',
    temperature: 0.5,
    max_tokens: 300,
  }),
});

Hugging Face

Hugging Face 提供对数千个开源模型的访问：

const response = await fetch('http://localhost:3000/model/custom-model-name/infer', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Input for the model',
    parameters: {
      // Model-specific parameters
    },
  }),
});

文档

• MCP 标准方法：所有 MCP 服务都应实现的标准方法文档。
• MCP 接口：MCP 协议的 TypeScript 接口定义。
• 架构：MCP 服务架构概述。

许可证

ISC