MCP Starter Kit

MCP服务器入门套件

用于构建模型上下文协议（MCP）服务器的生产就绪TypeScript模板。跳过样板，在几分钟内将工作工具运送给Claude和其他MCP客户。

包含什么

• 工作MCP服务器 使用官方 @modelcontextprotocol/sdk
• 3个示例工具 您可以按原样使用或调整：

- fetch_url --使用可配置的限制和域阻止获取web内容 - read_file / list_directory --具有路径遍历保护的安全文件系统访问 - transform_data --在JSON、CSV、TSV、Markdown表和纯文本之间转换

• TypeScript贯穿始终 --严格模式、键入输入/输出、Zod验证
• 错误处理模式 --每个工具都返回一个类型 ToolResult 具有ok/error判别功能
• 基于环境的配置 --所有限制和路径均可通过以下方式配置 .env
• 结构化日志记录 --仅stderr记录器（MCP协议使用stdout）
• 测试套件 --使用Vitest进行19次测试，涵盖所有三种工具
• 构建脚本 — npm run build, npm run dev, npm test, npm run typecheck

需求

• Node.js 18或更高版本
• npm 9或更高版本

快速开始

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env — at minimum, set FILE_READER_ROOT to a safe directory

# 3. Build
npm run build

# 4. Run
npm start

开发模式

npm run dev

用途 tsx 对于实时重新加载，开发过程中不需要构建步骤。

连接到克劳德桌面

将此添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上， %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-starter-kit/dist/index.js"],
      "env": {
        "FILE_READER_ROOT": "/path/to/allowed/directory",
        "LOG_LEVEL": "info"
      }
    }
  }
}

重新启动克劳德桌面。您的工具将出现在工具选择器中。

连接到克劳德代码

添加 .claude/settings.json:

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

工具参考

fetch_url

获取URL的文本内容。

返回响应正文、状态代码、内容类型和 truncated 如果超过响应，则标记 FETCH_MAX_BYTES.

read_file

读取配置中的文件 FILE_READER_ROOT.

路径遍历(../)在解析器级别被阻塞。

list_directory

列出配置的根目录中的文件和目录。

转换数据

在不同格式之间转换数据。

配置

所有配置都是通过环境变量进行的。看 .env.example 查看完整列表。

添加自己的工具

1. 创建 src/tools/my-tool.ts --导出一个返回的异步函数 ToolResult
2. 将输入/输出类型添加到 src/types.ts 使用Zod模式
3. 在中注册该工具 src/index.ts 随着 server.tool(name, description, schema, handler)
4. 在中编写测试 src/tools/my-tool.test.ts

所有三个示例工具使用的模式：

export async function myTool(input: MyToolInput): Promise> {
  // validate, execute, return { ok: true, data: ... } or { ok: false, error: "...", code: "..." }
}

项目结构

mcp-starter-kit/
├── src/
│   ├── index.ts          # Server entry point — tool registration
│   ├── config.ts         # Environment variable loading
│   ├── logger.ts         # Stderr logger
│   ├── types.ts          # Shared types and Zod schemas
│   └── tools/
│       ├── web-fetcher.ts
│       ├── web-fetcher.test.ts (add your own)
│       ├── file-reader.ts
│       ├── file-reader.test.ts
│       ├── data-transformer.ts
│       └── data-transformer.test.ts
├── dist/                 # Compiled output (after npm run build)
├── .env.example
├── package.json
├── tsconfig.json
└── vitest.config.ts

运行测试

npm test           # Run once
npm run test:watch # Watch mode

许可证

麻省理工学院