AI导哈

MCP服务器模板

一个最小化且文档齐全的模型上下文协议（MCP）服务器模板，用于构建自定义MCP工具。

  • by fellanH
  • TypeScript
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 fellanH/klar-mcp

使用说明

MCP服务器快速启动

一个最小的、记录良好的模型上下文协议（MCP）服务器模板。以此为起点构建自己的MCP工具。

什么是MCP？

这 模型上下文协议 是一个开放标准，允许AI助手（如Claude或Cursor）使用外部工具。把它想象成给克劳德双手与世界互动：

┌─────────────┐     MCP Protocol      ┌─────────────┐
│     AI      │ ◄──────────────────►  │ Your Server │
│  (Client)   │   JSON-RPC over       │   (Tools)   │
└─────────────┘      stdio            └─────────────┘

关键概念：

  • 服务器：公开工具的代码（此仓库）
  • 客户端：调用您的工具（Cursor、Claude Code等）的AI助手
  • 工具：AI可以通过结构化输入/输出调用的函数
  • 运输：客户端和服务器如何通信（通常是stdio）

快速开始

1.克隆和安装

git clone https://github.com/fellanH/klar-mcp.git
cd klar-mcp
npm install

2.建造

npm run build

3.配置您的客户端

将此服务器添加到MCP客户端配置中：

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "klar-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/klar-mcp/dist/index.js"]
    }
  }
}
Claude Code

运行：

claude mcp add klar-mcp node /absolute/path/to/klar-mcp/dist/index.js
Cursor
  1. 打开光标设置(Cmd+, 在macOS上， Ctrl+, 在Windows/Linux上）
  2. 搜索“MCP”或导航到 功能>MCP服务器
  3. 点击 添加新的MCP服务器
  4. 输入：
    • 名字: klar-mcp
    • 类型: command
    • 命令: node /absolute/path/to/klar-mcp/dist/index.js

或编辑 ~/.cursor/mcp.json 直接：

{
  "mcpServers": {
    "klar-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/klar-mcp/dist/index.js"]
    }
  }
}

4.测试

重新启动客户端（Claude Desktop、Claude Code或Cursor）。现在，您应该能够要求AI使用您的工具：

“使用hello_world工具问候我”

项目结构

klar-mcp/
├── src/
│   ├── index.ts          # Server entry point - handles MCP protocol
│   ├── types.ts          # Shared TypeScript types
│   └── tools/
│       ├── index.ts      # Tool registry - exports all tools
│       ├── hello-world.ts    # Example: simplest possible tool
│       ├── timestamp.ts      # Example: tool with enum options
│       ├── uuid.ts           # Example: tool with optional params
│       └── ...               # More example tools
├── dist/                 # Compiled JavaScript (generated)
├── package.json
└── tsconfig.json

运作原理

1.服务器(src/index.ts)

服务器做三件事：

  1. 创建MCP服务器 带有名称和版本
  2. 注册处理程序 用于列出和调用工具
  3. 通过stdio连接 这样客户端就可以与它进行通信
// Simplified version of src/index.ts
const server = new Server({ name: "klar-mcp", version: "1.0.0" }, {
  capabilities: { tools: {} }
});

// When client asks "what tools do you have?"
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: definitions  // Return all tool definitions
}));

// When client says "call this tool with these arguments"
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const handler = handlers.get(request.params.name);
  return handler(request.params.arguments);
});

// Start listening on stdin/stdout
const transport = new StdioServerTransport();
await server.connect(transport);

2.工具(src/tools/hello-world.ts)

每个工具有两个部分：

  • 定义：名称、描述和输入模式（AI看到的内容）
  • 处理器：实际运行的代码（您实现的内容）
export const helloWorld: ToolModule = {
  definition: {
    name: "hello_world",
    description: "A simple greeting tool",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" }
      }
    }
  },
  handler: async (args) => {
    const name = args?.name || "World";
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }]
    };
  }
};

3.书记官处(src/tools/index.ts)

所有工具都被收集到两个导出中：

  • definitions：工具模式数组（用于 ListTools)
  • handlers：名称地图→ 处理函数（for CallTool)

添加您自己的工具

看 docs/ADDING-TOOLS.md 获取分步指南。

快速版本：

  1. 创建 src/tools/my-tool.ts:
import { ToolModule } from "../types.js";

export const myTool: ToolModule = {
  definition: {
    name: "my_tool",
    description: "What this tool does",
    inputSchema: {
      type: "object",
      properties: {
        input: { type: "string", description: "The input" }
      },
      required: ["input"]
    }
  },
  handler: async (args) => {
    // Your logic here
    return {
      content: [{ type: "text", text: `Result: ${args.input}` }]
    };
  }
};
  1. 注册于 src/tools/index.ts:
import { myTool } from "./my-tool.js";
// ... add to tools array
  1. 重建： npm run build

包含示例工具

工具 描述 演示
hello_world 简单的问候 最小的工具结构
timestamp 获取当前时间 枚举参数
uuid 生成UUID 具有默认值的可选参数
base64 编码/解码 必需参数，错误处理
hash 生成哈希值 多种算法
json_format 格式化/验证JSON 复杂的输入验证
env_info 环境细节 系统交互
text_stats 文本分析 对象响应
regex_test 测试正则表达式模式 模式匹配
random_string 生成字符串 字符集
shell_command 运行shell命令 子进程执行

发展

# Build TypeScript
npm run build

# Build and run
npm run dev

# Run tests (if you add them)
npm test

了解更多

许可证

麻省理工学院

去建造吧！我完全允许您根据需要调整、共享和编辑此项目。我只想说，如果你创造了一些很酷的东西，你可以和我分享。我总是很高兴看到你创造了什么。

相关 MCP