poc-mcp-server

你是否正在学习如何构建一个MCP服务器，却不知道从哪里开始？或者需要一个完整但不过于复杂的项目来理解MCP的核心概念？poc-mcp-server正是这样一个理想的起点。

poc-mcp-server是一个概念验证性质的MCP服务器实现。它演示了如何使用TypeScript构建一个功能完整的MCP服务器，提供了对Loomers、表单、表单响应和项目等资源的访问和操作工具。对于想要学习MCP服务器开发模式的开发者来说，这是一个极好的学习范例。

项目基本信息

一、项目介绍

poc-mcp-server是一个演示性质的MCP服务器，它的代码结构清晰，注释完整，非常适合作为学习MCP服务器开发的入门材料。它实现了多个典型的MCP工具，涵盖了列表获取、分页、过滤和排序等常见模式。

该项目包含的工具围绕一个虚构的业务场景设计：管理Loomers（某种人员或实体）、表单、表单响应和项目。虽然数据是模拟的，但代码实现方式与实际项目高度一致。你可以在理解其架构后，轻松地将模式应用到自己的真实数据源上。

服务器使用TypeScript编写，并依赖pnpm作为包管理器。它包含了完整的开发、构建、测试和代码检查流程，是一个规范的Node.js项目。

二、核心优势

完美的学习范例：项目的代码量适中，结构清晰。它展示了如何组织MCP服务器的代码、如何定义工具、如何处理请求参数、如何实现分页和过滤等核心功能。对于任何想学习MCP服务器开发的开发者来说，这是一个可以直接参考的模板。

完整的功能演示：它不只是展示一个工具，而是演示了五种不同的工具，覆盖了列表查询和基于位置的查询等模式。每个工具都包含了可选参数的实现，展示了如何输入验证和错误处理。

现代化的开发工具链：项目使用了TypeScript、pnpm、Biome（代码检查和格式化）、Vitest（测试框架）。这些工具代表了当前JavaScript/TypeScript生态中的最佳实践。学习这个项目，也能帮助你了解现代Node.js项目的配置和工具链。

开箱即用的工程化配置：项目包含完整的package.json脚本（dev、build、start、test、lint），以及Docker和Smithery配置文件。你可以直接fork或克隆这个项目，作为自己MCP服务器开发的基础模板。

三、适用场景

场景一：学习MCP服务器开发。这是本项目最主要的用途。你可以通过阅读和运行这个项目，理解一个MCP服务器是如何构建的，包括如何设置开发环境、定义工具、处理请求等。

场景二：作为新项目的脚手架。如果你准备开发一个新的MCP服务器，可以以这个项目为基础进行修改。它已经配置好了TypeScript编译、测试框架和代码检查工具，你只需要替换业务逻辑即可。

场景三：面试准备和技术分享。这个概念验证项目可以作为一个很好的示例，向面试官或同事展示你对MCP协议的理解，以及你的TypeScript和工程化能力。

场景四：理解MCP工具的设计模式。通过研究它实现的五种工具，你可以学习到如何处理列表查询、如何实现分页、如何支持过滤和排序，以及如何设计基于位置的查询。

四、安装教程

由于这是一个Node.js项目，安装非常简单。

第一步：确保环境

• 安装Node.js 18或更高版本
• 安装pnpm包管理器（可以通过npm install -g pnpm安装）

第二步：克隆并安装

# 克隆项目
git clone https://github.com/BrunoSSantana/poc-mcp-server
cd poc-mcp-server

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 启动服务器（用于测试）
pnpm start

第三步：配置MCP客户端

要将其集成到Claude Desktop等MCP客户端中，需要在客户端配置文件中添加配置。以Claude Desktop为例，找到配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json，Windows: %APPDATA%\Claude\claude_desktop_config.json），添加：

{
  "mcpServers": {
    "poc-mcp-server": {
      "command": "node",
      "args": [
        "/你的完整路径/poc-mcp-server/build/index.js"
      ]
    }
  }
}

注意：需要将路径替换为克隆项目后build/index.js的绝对路径。

第四步：验证

重启MCP客户端后，AI应该可以调用getLoomers、getProjects等工具。

五、使用示例

由于这个服务器使用的是模拟数据，它的主要价值在于演示模式而非实际生产数据。以下是假想的对话示例。

示例一：获取Loomers列表

你问：“请列出所有的Loomers。”

AI会调用getLoomers工具，返回一个模拟的Loomer列表。

示例二：获取特定区域的Loomers

你问：“帮我找出位于某个区域的Loomers。”

AI会调用getLoomersInArea工具，并传入位置参数。

示例三：获取表单及其响应

你问：“我有哪些表单？给最新的三份表单。”

AI会调用getForms工具，并可能使用limit和sortBy参数。

示例四：分页查询项目

你问：“项目列表的第二页，每页显示5条。”

AI会调用getProjects工具，设置page: 2和limit: 5。

六、常见问题

问题一：运行pnpm install时提示找不到命令。

解决方案：这说明pnpm没有安装。请先运行npm install -g pnpm全局安装pnpm，然后再试。

问题二：配置到Claude Desktop后，AI找不到或无法调用工具。

解决方案：请确认你在配置中使用了build/index.js的绝对路径。同时检查.env.example文件，如果需要配置API端点或密钥，请复制为.env文件并填写正确的值。重启Claude Desktop前，请先确保构建成功（pnpm build）。

问题三：这个服务器似乎只返回模拟数据，能接入真实数据吗？

解决方案：可以。项目的核心框架是通用的，你需要修改src/tools/下的文件，将模拟数据返回替换为从你的真实数据库或API获取数据的逻辑。这也是该项目作为“概念验证”的意义——验证模式可行后，你可以替换数据源。

问题四：如何添加新的工具？

解决方案：在src/tools/目录下创建一个新文件，按照其他工具的格式实现工具的定义和处理逻辑，然后在src/index.ts中注册这个新工具即可。

问题五：项目只支持stdio传输吗？

解决方案：目前的实现主要聚焦于MCP核心功能。如果需要HTTP或SSE支持，可以参考其他MCP服务器项目进行扩展。

七、总结

poc-mcp-server是一个小而美的MCP服务器参考实现。它的首要价值不是提供即用的功能，而是作为一个“教学脚手架”存在。对于任何想要踏入MCP服务器开发领域的开发者来说，它是一个可以直接运行、阅读和修改的完整范例。

这个项目展示了如何组织TypeScript MCP项目、如何定义和注册多个工具、如何处理分页和过滤等通用模式，以及如何使用现代工程化工具链。它的代码量（15次提交记录，完整的src目录）恰到好处——不会简单到无参考价值，也不会复杂到难以理解。

如果你正计划编写自己的MCP服务器，我强烈建议你先克隆并运行poc-mcp-server。理解它的结构后，你会发现开发一个MCP服务器并没有想象中那么困难。这个小小的概念验证项目，可能是你进入MCP生态系统的第一块踏脚石。