Skip to main content
Glama
cs-roam-mcp

cs-roam-mcp

README.md
# cs-roam-mcp

真人 CS 第一人称漫游 MCP(Model Context Protocol)服务 —— 一句话:让任何基于 Three.js / React Three Fiber 的数字孪生、园区、楼宇可视化项目,**一行工具调用就拿到一套国产 3A 级 FPS 手感的第一人称漫游控制器源码**。

参数逆向整理自国产 3A 级 FPS 游戏的漫游控制器(移动 / 形体 / 视觉全套配置),已在数字孪生 Web 工程中以 TypeScript 复刻并通过 `tsc` 类型检查与线上验证。

## 特性

- **真·FPS 手感**:走 / 冲刺 / 下蹲 / 瞄准(ADS)四档速度,地面四档加速度逼近与衰减,空中操控衰减
- **跳跃系统**:`jumpVelocity = √(2·g·h)` 精确起跳、土狼时间(coyote 0.12s)、跳跃缓冲(0.13s)、落地下沉弹簧 + 镜头震动衰减
- **镜头表现**:步伐相位 bob(Y/X 双轴)、冲刺 FOV +6°、ADS FOV 52°、侧移滚转、鼠标尖峰过滤(>400px 剔除)
- **碰撞**:多边形足迹(footprint polygon)分轴滑动碰撞,建筑轮廓直接投影即可用
- **零依赖 MCP**:仅 Node 内置模块,stdio JSON-RPC 2.0,无需 `npm install`
- **可移植组件**:`FirstPersonWalk.portable.tsx` 无任何项目数据依赖,碰撞体 / 出生点 / 灵敏度全部走 props

## 快速开始

```bash
git clone https://github.com/dashizhihuan2018-source/cs-roam-mcp.git
```

### 注册到 WorkBuddy / Claude 等 MCP 宿主

在 MCP 配置(如 `~/.workbuddy/mcp.json` 或 `claude_desktop_config.json`)中添加:

```json
{
  "mcpServers": {
    "cs-roam": {
      "command": "node",
      "args": ["/你的路径/cs-roam-mcp/index.js"]
    }
  }
}
```

重启宿主后即可使用(WorkBuddy 用户需在连接器管理页对新服务点 Trust 启用)。

## 提供的工具

| 工具 | 用途 |
|------|------|
| `cs_roam_component` | 返回可移植组件 `FirstPersonWalk.portable.tsx` 完整源码(直接落盘即用) |
| `cs_roam_config` | 返回全套手感参数表(速度 / 加速度 / 重力跳跃 / 镜头 / 碰撞),含单位与出处说明 |
| `cs_roam_integrate` | 返回接入指南:Canvas 接线、OrbitControls 让位与恢复、指针锁定、HUD 提示样式 |
| `cs_roam_customize` | 按你的项目定制参数(身高 / 速度 / 灵敏度等),跳跃速度自动按 `√(2gh)` 推导 |

典型对话用法:

> 帮我把第一人称漫游加到这个 Three.js 场景里,建筑碰撞体用这几个多边形。

宿主会自动调用上述工具拿到源码与接线说明,直接写入你的工程。

## 组件依赖

`FirstPersonWalk.portable.tsx` 需要:

- React 18+
- `@react-three/fiber`(组件挂在 `<Canvas>` 内)
- three.js(r150+)

## 技术栈

Node.js ≥ 16(MCP 服务);TypeScript + React Three Fiber(漫游组件)。

## License

MIT