generic-mcp-server

🚀 通用 MCP 服务器

本项目是一个生产就绪的 Model Context Protocol (MCP) 服务器实现，运用 TypeScript 和 Express 构建，能让 AI 代理与外部 API 实现无缝连接，为开发人员提供了极大便利。

🚀 快速开始

安装

1. 克隆仓库：

git clone https://github.com/yourusername/generic-mcp-server.git
cd generic-mcp-server

2. 安装依赖项：

npm install

3. 配置环境：

cp .env.example .env

4. 将 API 凭据添加到 .env 文件中：

PORT=8089
ACCESS_TOKEN=your_movie_db_access_token

运行服务器

开发模式（带热重载）：

npm run dev

生产模式：

npm run build
npm start

服务器将在 http://localhost:8089（或 .env 文件中指定的端口）可用。

✨ 主要特性

• 完整实现 MCP 规范
• 使用 Server-Sent Events (SSE) 实现实时通信
• 模块化架构，便于扩展
• 内置电影数据库集成，用于搜索人员和发现影片
• API 响应的类型安全接口
• 全面错误处理
• 测试用例客户端作为参考

📦 安装指南

安装

1. 克隆仓库：

git clone https://github.com/yourusername/generic-mcp-server.git
cd generic-mcp-server

2. 安装依赖项：

npm install

3. 配置环境：

cp .env.example .env

4. 将 API 凭据添加到 .env 文件中：

PORT=8089
ACCESS_TOKEN=your_movie_db_access_token

运行服务器

开发模式（带热重载）：

npm run dev

生产模式：

npm run build
npm start

💻 使用示例

基础用法

本项目主要是一个服务器项目，以下是启动服务器的基础命令示例：

# 克隆仓库
git clone https://github.com/yourusername/generic-mcp-server.git
cd generic-mcp-server

# 安装依赖
npm install

# 配置环境
cp .env.example .env

# 添加 API 凭据到 .env 文件

# 开发模式运行
npm run dev

# 生产模式运行
npm run build
npm start

高级用法

在实际开发中，你可以根据需求对服务器进行扩展，例如添加新的 API 端点。以下是一个简单示例，假设你要添加一个新的 GET 端点 /new-endpoint：

import express from 'express';
const app = express();

app.get('/new-endpoint', (req, res) => {
  res.send('This is a new endpoint!');
});

const port = process.env.PORT || 8089;
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

📚 详细文档

概述

该项目展示了如何使用 @modelcontextprotocol/sdk 实现基于 Server-Sent Events (SSE) 的 MCP 服务器。它为开发人员提供了一个实用的参考，用于将 APIs 曝露给 AI 代理和大型语言模型（LLMs），重点在于电影数据库交互。实现细节可在 src/mcp/tools.ts、src/mcp/prompts.ts、src/helpers/ 目录及相关文件中找到。

什么是 MCP？

Model Context Protocol (MCP) 建立了一个标准化接口，使 AI 模型能够安全高效地与外部系统交互。它定义了以下结构化的框架：

• 资源：模型可以访问的数据对象
• 工具：模型可以调用的可执行函数
• 提示：指导模型交互的模板 这种标准化简化了将 AI 功能集成到现有应用程序和服务中的过程。更多文档请访问 Model Context Protocol 仓库。

API 参考

端点

| 端点 | 方法 | 描述 | |----------|--------|-------------| | /sse | GET | 用于 MCP 通信的服务器发送事件端点 | | /messages | POST | 客户端向 MCP 服务器发送消息的端点 |

MCP 组件

资源

• greeting://welcome：静态欢迎消息
• users://{userId}：动态用户数据资源

工具

该服务器实现了强大的电影数据库工具：

• movie_database_search_person：搜索演员、导演和其他电影从业人员，获取他们职业生涯、传记数据和电影作品的详细信息。
• movie_database_discover_films：高级电影发现功能，基于筛选条件推荐影片。

提示

MCP 定义了一系列提示模板，用于指导 AI 代理与外部系统的交互。这些提示包括：

1. 系统提示（System Prompt）：定义整个交互的上下文和目标。
2. 用户提示（User Prompt）：具体的操作指令。
3. 响应提示（Response Prompt）：规范 API 调用的结果格式。

电影数据库集成

服务器内置了对知名电影数据库的访问接口，支持以下操作：

1. 搜索电影、演员和导演信息
2. 获取电影详情及评价
3. 查找电影院映片时间表
4. 管理用户收藏列表 所有 API 调用均通过类型安全的接口进行封装，简化了开发流程。

🔧 技术细节

该项目使用 TypeScript 和 Express 构建，实现了基于 Server-Sent Events (SSE) 的 MCP 服务器。核心实现细节分布在多个文件和目录中，如 src/mcp/tools.ts 实现了具体的工具函数，src/mcp/prompts.ts 定义了提示模板，src/helpers/ 目录包含了一些辅助函数。通过模块化架构，开发人员可以方便地对服务器进行扩展和维护。同时，使用 @modelcontextprotocol/sdk 实现了 MCP 规范，确保了与 AI 代理和大型语言模型的交互的标准化。

📄 许可证

MIT