MCP Server Template

MCP 服务模板

前置条件

安装 LLM CLI

此项目需要安装 LLM CLI。你可以使用 Homebrew 安装：

brew install llm

安装后，运行以下命令，确保 llm 命令位于 PATH 中：

llm --version

开始使用

开发

1. 安装依赖：

   npm install
   

2. 启动支持热重载的开发服务：

   npm run dev
   

3. 构建项目：

   npm run build
   

4. 运行测试：

   npm test
   

5. 启动生产服务：

   npm start
   

Architect 工具

Architect 工具（src/tools/architect.ts）提供了一个接口，用于通过 LLM CLI 获取架构设计反馈。它会保留对话上下文，并处理应用程序与 LLM CLI 之间的通信。

功能

• 在多次交互中保留对话上下文
• 通过 LLM CLI 处理命令执行
• 提供错误处理和日志记录
• 支持新建对话和继续讨论

要求

• 必须安装 LLM CLI，且该命令位于 PATH 中（参见“前置条件”部分）
• 应为 LLM CLI 正确配置环境变量

测试

此模板内置了用于本地测试的 TestClient 和用于可视化调试的 MCP Inspector。

使用 TestClient

TestClient 提供了一种简单的方式来测试工具：

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

使用 MCP Inspector

此模板内置了 MCP Inspector，可用于对工具进行可视化调试：

1. 启动 Inspector：

   npx @modelcontextprotocol/inspector node dist/index.js
   

2. 在 http://localhost:5173 打开 Inspector UI

Inspector 提供：

• 用于测试工具的可视化界面
• 实时请求/响应监控
• 工具元数据检查
• 交互式测试环境

使用 Cursor 进行本地测试

要使用 Cursor 在本地测试 MCP 服务：

1. 构建并链接软件包：

   npm run build
   npm run link
   

2. 验证二进制文件是否正常工作：

   npx architect-test-mcp-tool
   

3. 将服务添加到 Cursor：

   • 打开 Cursor 设置
   • 转到 Features 选项卡
   • 向下滚动到 MCP Servers 部分
   • 点击“Add Server”
   • 选择“Command”类型
   • 为其命名（例如，“Local Example Tool”）
   • 输入命令：npx architect-test-mcp-tool
   • 点击 Confirm

4. 检查 MCP Servers 部分是否显示你的服务正在运行，以确认服务已在 Cursor 中正常启动。

注意：如果你修改了代码，请记得重新构建并链接：

npm run build
npm run link

测试完成后，可以取消链接该软件包：

npm run unlink

这将移除开发期间创建的全局符号链接。

故障排除

使用 MCP Inspector

MCP Inspector 是用于调试和检查 MCP 服务的实用工具。使用方法如下：

1. 首先，构建项目：

   npm run build
   

2. 运行 Inspector：

   npx @modelcontextprotocol/inspector node dist/index.js
   

Inspector 提供了一个 Web 界面，可用于：

• 查看所有可用工具及其架构
• 交互式测试工具调用
• 检查请求/响应载荷
• 调试服务与客户端之间的通信问题