ASDM MCP Server

纯内网、无外网依赖、无本地工具的 TypeScript MCP Server，基于 @modelcontextprotocol/sdk 实现，完全符合官方 MCP 协议规范。

🚀 核心特性

• 🔒 纯内网运行：不依赖任何外网资源
• 🔄 命令转发模式：监听命令并转发到云端 API 执行
• 📝 结构化日志：完整的事件日志输出，携带 sessionId
• ⚙️ 可配置开关：支持事件上报、详细日志等开关控制
• 📋 MCP 规范兼容：完全符合官方协议，支持 Claude/Cursor/自研 Agent

🎯 核心功能

1. 命令监听与转发

• 自动扫描 .codebuddy/commands/ 目录发现所有命令
• 读取命令对应的 .md 文件内容
• 将命令内容、sessionId 发送到云端 API
• 云端返回执行指令，AI 再执行后续步骤

2. 事件上报

• SESSION_START：客户端连接 MCP Server 成功后触发
• SESSION_END：客户端断开连接或进程退出时触发
• tool_call：每次工具调用时上报
• 上报到 POST /api/reporting/events
• 所有事件携带 sessionId

🛠 可用工具

ASDM 命令工具

• asdmCommandReport - 执行 ASDM 命令上报，仅上报命令执行事件
• asdmCommandExecute - 执行 ASDM 命令，读取命令文件并发送到远端 API 执行

参数（两个工具相同）： | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | commandName | string | 是 | 命令名称，如 /asdm-git-commit-message | | sessionContent | string | 是 | 当前会话内容（用于上下文） |

支持的命令

通过自动扫描 .codebuddy/commands/ 目录发现，当前支持：

| 命令 | 描述 | MD 文件路径 | |------|------|-------------| | /asdm-context-build | 构建上下文 | .codebuddy/commands/asdm-context-build.md | | /asdm-context-update | 更新上下文 | .codebuddy/commands/asdm-context-update.md | | /asdm-git-commit-message | 生成 Git 提交信息 | .codebuddy/commands/asdm-git-commit-message.md | | /asdm-git-commit | 执行 Git 提交 | .codebuddy/commands/asdm-git-commit.md | | /asdm-git-push | 执行 Git 推送 | .codebuddy/commands/asdm-git-push.md | | /asdm-start-project | 启动项目 | .codebuddy/commands/asdm-start-project.md |

项目结构

asdm-mcp-server/
├── src/
│   ├── index.ts          # 主程序入口（MCP Server、工具处理、事件上报）
│   ├── config.ts         # 配置管理（环境变量加载）
│   ├── types.ts          # 类型定义（接口、事件类型、命令扫描）
│   ├── logger.ts         # 结构化日志记录器
│   └── reporter.ts       # 事件上报器
├── .codebuddy/commands/  # 命令定义文件（自动扫描发现）
├── mcp.json              # MCP Server 配置
├── .env                  # 环境变量配置
├── package.json
├── tsconfig.json
└── test-local.js         # 本地测试脚本

快速开始

1. 安装依赖

npm install

2. 配置环境变量

复制 .env.example 为 .env 并修改配置：

cp .env.example .env

3. 构建项目

npm run build

4. 运行服务器

# 开发模式
npm run dev

# 生产模式
npm start

5. 本地测试

node test-local.js

配置说明

环境变量

| 变量名 | 说明 | 默认值 | |-------|------|--------| | ENABLE_REPORTING | 是否启用事件上报 | false | | ENABLE_DETAILED_LOGGING | 是否启用详细日志 | false | | API_BASE_URL | 云端 API 基础地址 | http://localhost:3000 | | REPORTING_API_PATH | 事件上报 API 路径 | api/reporting/events | | EXECUTE_API_PATH | 命令执行 API 路径 | api/commands/execute | | REPORTING_API_TIMEOUT | 上报 API 超时（毫秒） | 30000 | | REPORTING_API_RETRIES | 上报 API 重试次数 | 3 | | API_TIMEOUT | 命令执行 API 超时（毫秒） | 30000 | | API_RETRIES | 命令执行 API 重试次数 | 3 | | CLIENT_USERNAME | 客户端用户名（可选） | 自动获取系统用户名 | | CLIENT_ENVIRONMENT | 客户端环境标识（可选） | 自动检测平台 |

客户端用户名自动获取

• Windows: 自动使用 %USERNAME% 环境变量
• Linux/Mac: 自动使用 $USER 或 $LOGNAME 环境变量
• 如需覆盖，可在 .env 中设置 CLIENT_USERNAME

日志文件

• 路径: c:\users\edz\.asdmmcpserver.log
• 格式: 结构化 JSON 格式
• 自动清理: 保留最近 7 天的日志
• 输出: 同时输出到控制台和文件

事件生命周期

SESSION_START
  ├── tool_call
  ├── ... (多个工具调用)
  └── tool_call
SESSION_END

事件上报格式

会话开始事件

{
  "type": "session_start",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "sessionId": "1700000000-abc1234"
}

命令执行事件

{
  "type": "command_executed",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "sessionId": "1700000000-abc1234",
  "data": {
    "command": "/asdm-git-commit-message",
    "success": true,
    "instructions": "执行 git add . && git commit -m 'feat: add new feature'"
  }
}

工具调用事件

{
  "type": "tool_call",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "sessionId": "1700000000-abc1234",
  "data": {
    "toolName": "asdmCommand",
    "command": "/asdm-git-commit-message",
    "success": true
  }
}

云端 API 接口

命令执行接口

POST /api/commands/execute

请求格式

{
  "event": "EXECUTE_COMMAND",
  "batchId": "1700000000-abc1234",
  "eventCount": 1,
  "events": [{
    "command": "/asdm-git-commit-message",
    "sessionContent": "用户：帮我提交代码\n助手：好的",
    "mdFilePath": ".codebuddy/commands/asdm-git-commit-message.md",
    "mdFileContent": "follow .asdm/toolsets/basic-tools/actions/asdm-git-commit-message.md",
    "timestamp": "2024-01-01T00:00:00.000Z",
    "sessionId": "1700000000-abc1234"
  }]
}

响应格式

{
  "success": true,
  "instructions": "1. Run: git status\n2. Run: git add .\n3. Run: git commit -m 'feat: add new feature'\n4. Run: git push"
}

事件上报接口

POST /api/reporting/events

架构设计

用户 → AI Client → MCP Server (asdm-mcp-server) → 云端 API
                     ↓                                ↓
                事件上报                        返回执行指令
                  ↓                                ↓
          POST /api/reporting/events          AI 执行后续步骤

核心流程

1. 命令发现：启动时自动扫描 .codebuddy/commands/ 目录
2. 工具调用：AI 发起 asdmCommand 调用
3. 文件读取：读取对应 .md 命令文件内容
4. 云端转发：将命令文件内容 + sessionId 发送到云端 API
5. 指令返回：云端处理后返回可执行指令
6. AI 执行：AI 收到指令后执行后续操作
7. 事件上报：上报会话生命周期事件（session_start/end、tool_call）

部署说明

内网部署

1. 确保所有依赖包在内网 npm 仓库可用
2. 配置云端 API 地址为内网地址
3. 设置适当的环境变量

容器化部署

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/

CMD ["node", "dist/index.js"]

故障排除

常见问题

1. 连接云端 API 失败：检查 API_BASE_URL 配置和网络连接
2. 事件上报失败：检查 ENABLE_REPORTING 设置和 API 接口
3. 命令执行失败：确认云端 API 已实现对应命令处理逻辑

日志分析

查看结构化日志，分析事件和命令调用的执行情况。所有日志均包含 sessionId。

许可证

MIT License