AI导哈

MCP服务器模板工具包

一个用于快速构建模型上下文协议（MCP）服务器的TypeScript模板，包含预置工具和完整开发环境配置。

  • by idapixl
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 idapixl/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<T> 具有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的文本内容。

参数 类型 必填 说明
url string yes 要获取的HTTP或HTTPS URL
headers object 否 其他请求标头
timeout_ms number no 请求超时（100-30000ms，默认来自env）

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

read_file

读取配置中的文件 FILE_READER_ROOT.

参数 类型 必填 说明
path string yes 根的相对路径
encoding utf8 或 base64 no 编码（默认值：utf8）
max_bytes number no 要读取的最大字节数（默认值：1MB）

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

list_directory

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

参数 类型 必填 说明
path string no 相对目录路径（默认值： .)
recursive boolean no 列出嵌套文件（默认值：false）

转换数据

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

参数 类型 必填 说明
input string yes 原始输入数据
from_format json|csv|tsv|text yes 输入格式
to_format json|csv|tsv|markdown_table|text_summary yes 输出格式
options.pretty boolean no 漂亮的打印JSON（默认值：true）
options.include_header boolean 否 包括CSV/TSV标题行（默认值：true）
options.delimiter string no CSV/TSV解析的自定义分隔符

配置

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

变量 默认值 描述
SERVER_NAME mcp-starter-kit 向客户端报告服务器标识
SERVER_VERSION 1.0.0 服务器版本
FETCH_MAX_BYTES 1048576 web提取器的最大响应大小（字节）
FETCH_TIMEOUT_MS 10000 默认获取超时（ms）
FETCH_BLOCKED_DOMAINS （空） 逗号分隔的屏蔽主机名
FILE_READER_ROOT ./workspace 文件访问的根目录
TRANSFORMER_MAX_INPUT 50000 变压器的最大输入字符数
LOG_LEVEL info 日志记录级别（调试/信息/警告/错误）

添加自己的工具

  1. 创建 src/tools/my-tool.ts --导出一个返回的异步函数 ToolResult<YourType>
  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<ToolResult<MyToolOutput>> {
  // 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

许可证

麻省理工学院

相关 MCP