AI导哈

MCP服务器启动模板

一个基于TypeScript构建的极简、生产就绪的MCP服务器模板，允许用户通过Claude、Cursor或任何MCP兼容的AI代理与产品交互。

  • by SoftwareSavants
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 SoftwareSavants/mcp-starter

使用说明

MCP服务器启动模板

一个用TypeScript构建的最小的、可用于生产的MCP服务器模板。克隆它，用API替换示例工具，您的用户可以通过Claude、Cursor或任何兼容MCP的AI代理与您的产品交互。

精益设计 --仅公开用户需要的内容，并提供令牌高效的工具描述和结构化的响应。

快速开始

# Clone
git clone https://github.com/SoftwareSavants/mcp-starter.git
cd mcp-starter

# Install
npm install

# Configure (pre-filled with DummyJSON — works out of the box)
cp .env.example .env

# Build & run
npm run build
npm start

然后添加到您的Claude Desktop配置中(~/Library/Application\ Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-product": {
      "command": "node",
      "args": [
        "--env-file=path/to/mcp-starter/.env",
        "path/to/mcp-starter/dist/index.js"
      ]
    }
  }
}

运输方式

此模板支持两种传输模式。使用适合您部署的选项：

标准（默认） HTTP+OAuth
认证 API密钥通过env var OAuth 2.1（PKCE）
最佳 本地开发，克劳德桌面 生产，多用户，远程
跑 npm start npm run start:http

Stdio模式（API密钥）

默认值。集 API_BASE_URL 和 API_KEY 作为环境变量-服务器使用密钥对所有API调用进行身份验证。

HTTP模式（OAuth）

运行一个完全支持OAuth 2.1的Express服务器。MCP服务器充当代理——它将身份验证委托给您的上游OAuth提供商（例如您产品的现有OAuth服务器）。

# Required environment variables for OAuth mode
export API_BASE_URL="https://api.yourproduct.com"
export OAUTH_AUTHORIZATION_URL="https://auth.yourproduct.com/authorize"
export OAUTH_TOKEN_URL="https://auth.yourproduct.com/token"
export OAUTH_USERINFO_URL="https://api.yourproduct.com/userinfo"
export OAUTH_CLIENT_ID="your-oauth-client-id"
export OAUTH_CLIENT_SECRET="your-oauth-client-secret"
export OAUTH_SCOPES="read,write"           # comma-separated
export OAUTH_ISSUER_URL="https://mcp.yourproduct.com"  # optional, defaults to http://localhost:3000
export PORT=3000                           # optional

npm run start:http

HTTP模式的Claude桌面配置：

{
  "mcpServers": {
    "my-product": {
      "url": "https://mcp.yourproduct.com/mcp"
    }
  }
}

它是如何工作的：

  1. 客户端连接到 /mcp 并被重定向到您的OAuth提供商
  2. 用户授权MCP客户端使用您的服务
  3. 客户端接收访问令牌，并将其与每个MCP请求一起发送
  4. 服务器验证令牌并使用它代表用户调用API

包含内容

  • src/index.ts --服务器入口点、注册工具、选择传输模式
  • src/tools/ -用API替换的示例工具（列表、获取、创建、搜索）
  • src/auth.ts -API密钥和OAuth令牌身份验证
  • src/types.ts --共享类型
  • src/transports/stdio.ts --标准传输（默认）
  • src/transports/http.ts --使用OAuth中间件的HTTP传输
  • src/oauth-provider.ts --代理OAuth提供程序配置
  • 内置错误处理和用户友好的消息
  • 令牌高效工具描述（精简，不臃肿）

如何自定义

1.定义你的工具

编辑 src/tools/ --每个文件导出一个工具。工具具有：

export const listItems: Tool = {
  name: "list_items",
  description:
    "List items with optional filters. Returns name, ID, and status.", // Keep it SHORT
  inputSchema: {
    type: "object",
    properties: {
      status: {
        type: "string",
        enum: ["active", "archived"],
        description: "Filter by status",
      },
      limit: { type: "number", description: "Max results (default 10)" },
    },
  },
  handler: async (args) => {
    const data = await api.get("/items", { params: args });
    // Return ONLY what the agent needs — not the full API response
    return data.items.map((i) => ({
      id: i.id,
      name: i.name,
      status: i.status,
    }));
  },
};

2.连接您的API

更新 src/auth.ts 使用您的身份验证方法和 API_BASE_URL 在env中。

3.配置OAuth（如果使用HTTP模式）

更新 src/oauth-provider.ts 使用您的令牌验证逻辑。默认使用userinfo端点——使其适应您的服务验证令牌的方式（JWT验证、自检端点等）。

4.保持身材苗条

  • 最多5-10个工具。 只暴露用户通过AI实际做了什么。
  • 简短描述。 一句话。LLM读取每个请求中的每个工具描述。
  • 结构化响应。 返回 { id, name, status } 不是完整的数据库行。
  • 没有嵌套的JSON blob。 尽可能压平。

设计原则

此模板遵循“构建精益”理念：

  1. 最小刀具表面 --更少的工具=代理每次都选择正确的工具
  2. 令牌高效描述 --工具描述中的每个字符在每次请求时都会消耗令牌
  3. 结构化响应 --保持上下文窗口精简的干净返回
  4. 优雅地失败 --清除代理可以转发给用户的错误消息

需要生产MCP服务器吗？

此模板可帮助您开始。适用于具有身份验证、权限、文档和持续维护的生产级MCP服务器-- 和我们聊聊.

软件野人 --AI原生产品工作室。我们构建了精简的MCP服务器，不会使上下文窗口膨胀。

许可证

麻省理工学院

相关 MCP