MCP TypeScript Stdio 示例项目

这是一个可分发的 Model Context Protocol (MCP) 服务端示例，采用了 stdio 协议进行通讯。

目录结构

项目采用了标准推荐的 src 布局：

• src/: 源代码目录
  • index.ts: 主入口文件
  • resources/: MCP 资源定义
  • tools/: MCP 工具定义
• dist/: 编译后的 JavaScript 输出
• package.json: 包含打包元数据和入口点配置

如何作为用户直接运行

如果你将此项目发布到 npm，其他用户无需手动下载代码，可以直接通过 npx 运行：

# 如果已发布到 npm
npx stdio-node-demo

或者从 GitHub 仓库直接运行（如果配置了 GitHub Actions 或其他分发方式）：

# 替换为你的 GitHub 仓库地址
npx github:YOUR_USERNAME/mcp-hello-world-ts

本地开发与运行

1. 安装环境

npm install

2. 构建项目

编译 TypeScript 源代码到 JavaScript：

npm run build

3. 运行服务端

项目配置了 stdio-node-demo 入口点，可以直接运行：

npm start

或者直接使用 node：

node dist/index.js

4. 测试验证

使用 MCP Inspector 进行测试：

npx @modelcontextprotocol/inspector node dist/index.js

或者运行集成测试：

npm test

分发到公共仓库 (npm) 的建议

如果你想让用户直接通过 npx stdio-node-demo 运行：

1. 注册 npm 账号。
2. 在项目根目录运行 npm run build 构建项目。
3. 使用 npm publish 将构建好的包发布。

发布后，用户的运行体验将非常顺滑：

npx stdio-node-demo

在 Claude Desktop 中的配置示例：

{
  "mcpServers": {
    "stdio-node-demo": {
      "command": "npx",
      "args": [
        "stdio-node-demo"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

或者使用本地开发版本：

{
  "mcpServers": {
    "stdio-node-demo": {
      "command": "node",
      "args": [
        "/path/to/mcp-hello-world-ts/dist/index.js"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

环境变量配置示例

本项目演示了两种配置环境变量的方式：

1. 使用 .env 文件（本地开发推荐）

在项目根目录下创建 .env 文件，你可以配置自定义的问候语前缀：

GREETING_PREFIX="你好"

服务端在初始化时会调用 dotenv 加载 .env 文件，你可以通过 say_greeting 工具来验证配置是否生效。

2. 在 Claude Desktop 中直接配置

如果你在 Claude Desktop 中使用此项目，可以在配置文件的 env 字段中注入环境变量：

{
  "mcpServers": {
    "stdio-node-demo": {
      "command": "node",
      "args": [
        "/path/to/mcp-hello-world-ts/dist/index.js"
      ],
      "env": {
        "GREETING_PREFIX": "尊敬的"
      }
    }
  }
}

3. 可用工具演示

• helloTool(message?): 回显消息或返回默认问候语。如果提供了 message 参数，则回显该消息；否则返回 "Hello, World!"。
• add_numbers(a, b): 基础数值加法，将两个数字相加并返回结果。
• say_greeting(name): 演示从环境变量获取前缀并拼接姓名。从环境变量 GREETING_PREFIX 读取前缀（默认为 "Hello"），然后与提供的姓名拼接。

4. 安全建议

• 不要提交 .env：敏感信息（如 API Key）应仅存在于本地 .env 中，本项目已将其加入 .gitignore。
• 配置模板：参考 .env.example 创建你自己的本地配置。

使用 with Claude Desktop

你可以配置 Claude Desktop 或任何 MCP 客户端来使用此服务器作为插件/工具，通过指定启动 MCP 服务器的命令。

配置示例

使用 npm 包（推荐）

如果你通过 npm 安装了包，可以在 Claude Desktop 设置中添加以下配置：

选项 1: 使用 npx（推荐 - 适用于所有环境）

{
  "mcpServers": {
    "stdio-node-demo": {
      "command": "npx",
      "args": [
        "stdio-node-demo"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

选项 2: 直接路径（需要完整路径）

{
  "mcpServers": {
    "stdio-node-demo": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/stdio-node-demo/dist/index.js"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

注意： 根据你的系统调整路径：

• macOS/Linux (全局安装): /usr/local/lib/node_modules/stdio-node-demo/dist/index.js
• Windows (全局安装): %APPDATA%\\npm\\node_modules\\stdio-node-demo\\dist\\index.js
• 本地安装: ./node_modules/stdio-node-demo/dist/index.js

使用源代码

如果你克隆了仓库，可以在 Claude Desktop 设置中添加以下配置：

{
  "mcpServers": {
    "stdio-node-demo": {
      "command": "node",
      "args": [
        "/path/to/mcp-hello-world-ts/dist/index.js"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

• 将 /path/to/mcp-hello-world-ts/ 替换为你克隆此仓库的完整路径。
• 确保在启动 Claude Desktop 之前已构建项目（npm run build）。

项目结构

.
├── src/
│   ├── index.ts                # 主 MCP 服务器入口点
│   ├── resources/
│   │   └── helloResource.ts    # MCP 资源定义
│   └── tools/
│       └── helloTool.ts        # MCP 工具定义
├── dist/                       # 编译后的 JS 输出
├── package.json
├── tsconfig.json
├── README.md
└── ...

自定义

• 要添加新工具或资源，在 src/resources/ 或 src/tools/ 中创建新文件，并在 src/index.ts 中注册它们。
• 修改 helloResource.ts 或 helloTool.ts 来更改问候语或添加其他功能。

License

MIT License

Author

• @snoopdave