MCP 本地开发框架与服务端实现

关键词

开发工具本地框架API 端点管理音频/图片媒体端点LLM 集成

使用说明

  • 项目简介

    • 这是一个基于 MCP（Model Context Protocol）的本地模组化后端框架，能够托管资源、注册和执行工具、并提供用于 LLM 的提示模板等能力。核心通过 MCP 服务器来暴露可被客户端（LLM）查询和调用的能力，且提供文件化的 API 路由和媒体资源端点的管理工具，支持通过多种传输方式工作（包括标准输入输出、网页端口和 Docker/容器化场景）。

  • 主要功能点

    • MCP 服务器核心能力：通过 MCP 的服务器组件接收客户端请求、处理请求、返回标准化的 JSON-RPC 风格响应。
    • 资源、工具、媒体端点的托管与管理：可以通过 MCP 工具向服务器注册新的 API 端点、媒体端点以及相关资源，并在运行时动态扩展能力。
    • 自动化 API 路由：基于 file-scan 的路由发现，自动加载 api 文件夹下的端点实现，生成可调用的 HTTP 处理器集合。
    • 数据与日志能力：内置数据库模型（使用 MSW 数据工厂）与日志记录，用于在本地开发阶段模拟真实数据和请求日志。
    • 多种传输方式：当前实现提供 STDIO 传输，以及通过 Docker Compose 在本地容器中运行的 MCP 服务器，便于在本地端到端测试。
    • 示例与模板：提供若干模板与示例代码，帮助快速生成新的端点、媒体端点，以及在 MCP 客户端中快速上手。

  • 安装步骤

    • 需求：Node.js 版本与环境配置符合仓库要求（通常为 Node.js 环境，若使用 Docker 则需要 Docker 和 docker-compose）。
    • 依赖安装：在项目根目录执行 npm install。
    • 本地启动（Docker 模式）：
      • 通过 npm start 启动 Docker 容器化的本地服务（框架自带的端点服务）。
    • 本地开发模式（不使用 Docker）：
      • 使用 npm run dev 进行本地开发热加载与测试。
    • MCP 服务运行方式
      • MCP 服务提供基于标准输入/输出（STDIO）的传输模式，启动后会监听端点并暴露工具与资源管理能力。

  • MCP 服务器配置（给 MCP 客户端的配置信息，不需要直接运行代码）

    • JSON 配置示例（请替换为你实际的项目绝对路径和端口等信息）： { "mcpServers": { "LocalMockAPIServer": { "command": "node", "args": [ "<absolute-path-to-your-project>/src/mcp/server.js" ] // 注释：请将 <absolute-path-to-your-project> 替换为你本地项目的完整路径 // 该配置用于 MCP 客户端在本地启动并连接到 MCP 服务器的命令及参数 } } }
    • 配置说明
      • server name：LocalMockAPIServer（可自定义，用于标识不同的 MCP 服务实例）
      • command：用于启动 MCP 服务器的可执行程序，一般为 node
      • args：执行命令的参数，需指向 MCP 服务器入口文件，例如 src/mcp/server.js 的绝对路径
      • MCP 客户端仅需要读取此配置以发起连接，不需要修改服务器端代码

  • 基本使用方法

    • 启动服务器后，客户端可通过 MCP 提供的工具来创建新 API 端点、媒体端点等，服务器将负责持久化到本地文件系统以及提供对外 API 的路由支持。
    • 通过浏览器访问或通过 /logs 查看请求日志，验证请求和响应行为是否符合预期。
    • 若要扩展端点，只需在 api 目录新增 api.ts 并确保在代码中返回符合 MCP 约定的处理器数组即可。
    • 开发过程可以结合示例模板（如 api.custom.template.ts、media.template.ts 等）快速生成新的端点实现。

服务器信息

访问项目