Generic MCP Server

通用 MCP 服务

一个使用 TypeScript 和 Express 构建的可用于生产环境的 Model Context Protocol（MCP）服务实现，旨在将 AI Agent 与外部 API 无缝连接。

概述

本项目展示了如何使用 @modelcontextprotocol/sdk 实现基于 Server-Sent Events（SSE）的 MCP 服务。它为开发者提供了一个实用示例，说明如何向 AI Agent 和大语言模型（LLM）开放 API，重点展示与电影数据库的交互。

实现细节可在 src/mcp/tools.ts、src/mcp/prompts.ts、src/helpers/ 目录及相关文件中找到。

什么是 MCP？

Model Context Protocol（MCP）为 AI 模型与外部系统进行安全、高效交互建立了标准化接口。它定义了一个结构化框架，包括：

• 资源：模型可以访问的数据对象
• 工具：模型可以调用的可执行函数
• 提示词：用于引导模型交互的模板

这种标准化简化了将 AI 功能集成到现有应用和服务中的过程。

如需完整文档，请访问 Model Context Protocol 仓库。

主要功能

• 完整实现 MCP 规范
• 通过 Server-Sent Events（SSE）进行实时通信
• 模块化架构，便于扩展
• 内置电影数据库集成，可搜索电影从业者并发现影片
• API 响应的类型安全接口
• 全面的错误处理
• 用于测试和参考的示例客户端

先决条件

• Node.js 18 或更高版本
• npm 或 yarn 包管理器

开始使用

安装

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 文件中指定的端口）。

API 参考

端点

端点	方法	描述
/sse	GET	用于 MCP 通信的 Server-Sent Events 端点
/messages	POST	客户端向 MCP 服务发送消息的端点

MCP 组件

资源

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

工具

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

• movie_database_search_person：搜索演员、导演和电影行业专业人士，并获取其职业经历、个人传记和作品列表等详细信息。
• movie_database_discover_films：高级影片发现功能，可按演员阵容、类型、上映日期、评分等进行筛选。

提示词

• greeting：友好的用户问候语
• help：详细的命令帮助
• ask-question：用于引导对话的问题模板
• error：优雅处理错误的提示词

电影数据库功能

该服务可访问 The Movie Database（TMDB）API，提供以下功能：

• 搜索电影行业专业人士，包括演员和导演
• 发现电影，支持多种筛选选项：
  • 按上映日期、热度或评分筛选
  • 按演员或剧组成员筛选
  • 按类型、关键词或公司筛选
  • 按片长或语言筛选
  • 按变现类型筛选（免费、订阅、租赁等）

环境配置

变量	描述	默认值
PORT	服务端口号	8089
ACCESS_TOKEN	电影数据库 API 的身份验证令牌	必填

使用示例客户端进行测试

此仓库包含一个演示客户端，展示了如何连接 MCP 服务并与之交互：

npm run client

客户端将：

• 与服务建立连接
• 显示可用的资源、工具和提示词
• 读取问候资源
• 演示工具用法
• 获取提示词模板

与 AI 模型集成

此服务可与任何支持 MCP 协议的大模型集成。标准化接口确保与各种 AI 框架和平台兼容。

架构

此项目采用模块化架构：

• src/mcp/：MCP 协议的核心实现
• src/helpers/：特定于 API 的辅助函数
• src/utils/：实用函数和共享代码
• src/types.ts：TypeScript 接口定义

可用接口

此项目包含用于 API 响应的类型化接口：

• ApiResponse<T>：通用 API 响应封装，包含数据、错误和状态字段
• ApiConfig：API 客户端配置，包含 baseUrl 和可选请求头

这些接口有助于确保处理 API 数据时的类型安全。

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT