feishu_mcp：个人本地开发工作台 MCP

部署前请先阅读 SECURITY.md。每台电脑必须使用自己的 .env、MCP_AUTH_TOKEN、授权目录、ngrok 地址和 Aily MCP 配置。不要共享或提交这些信息。

这是一个运行在你自己电脑上的 MCP（Model Context Protocol）服务。它让飞书 Aily工作台在受控范围内访问本机项目：读写文件、查看 Git、运行构建与测试、检查 Android或 Windows 开发环境，并安全导入二进制制品。

你的 Aily 工作台  →  HTTPS 隧道  →  你电脑上的 MCP  →  你的项目目录与工具链
                         Bearer 鉴权       目录边界、审批、审计和限额

源代码可以通过 Git 分享；Token、ngrok authtoken、.env、日志、审批数据、构建输出和个人路径不能分享。

10 分钟个人接入

1. 克隆并安装

git clone https://github.com/zhuxice-ctrl/feishu_mcp.git
cd feishu_mcp
npm install

2. 创建自己的本地配置

复制 .env.example 为 .env，然后只填写自己的项目目录和随机生成的 Token。不要把其他电脑的 .env 复制过来。

# 只授权自己的项目根目录；可用逗号分隔多个目录
ALLOWED_DIRS=F:\MyProjects

# 自己生成的长随机值；不要提交、截图或发送给他人
MCP_AUTH_TOKEN=<your-own-random-token>

# 个人部署的默认安全模式
AUTH_MODE=pin
AUTH_PIN=<your-own-strong-pin>
AUTH_USER_HEADER=x-aily-user

# 公网可达的自有主机名（Cloudflare 命名隧道前置的域名，见下文）
PUBLIC_HOST=mcp.example.com

# 命令默认仍需确认
OWNER_COMMAND_POLICY=approval

AUTH_MODE=none 仅适合完全由你自己控制的个人入口；即使使用它，也应保留MCP_AUTH_TOKEN。

3. 启动本地 MCP 与公网连接器

本地 MCP 与公网传输彼此解耦。Windows 推荐双击仓库根目录的：

start-feishu-mcp.bat

启动器只负责本地服务：它会构建服务、检查本地健康状态并启动 node dist/index.js，不会替你再启动任何隧道进程。它从 .env 读取 PUBLIC_HOST 并打印预期公网地址；公网连接器是否健康由下面第 4 步的手动 Tunnel supervisor 或scripts\test-cloudflare-tunnel.ps1 检查。你也可以手动运行：

npm run build
npm start

本地健康检查：

Invoke-RestMethod http://127.0.0.1:3000/health

正常时应返回 status: ok，并报告 42 个工具。若你使用 Clash Fake-IP，对公网/health 的回访失败只说明反向探测受限；本地服务和连接器仍可正常工作。

4. 先选择公网传输

在配置隧道前，先确定两件事：你使用 Cloudflare 还是 ngrok，以及是否拥有一个可专用于此 MCP 的独立域名。

选择	是否有独立 MCP 域名	建议
Cloudflare	有	使用 Cloudflare 命名隧道，并分配 `mcp.<你的域名>` 等专用子域名。这是主路径。
Cloudflare	没有	不要默认把现有业务域名暴露给本 MCP；建议先注册专用域名，或暂时使用 ngrok。
ngrok	不限	使用自己的 ngrok 账号和 HTTPS 地址；适合临时接入、没有独立域名时使用，或作为 Cloudflare 的回滚方案。

同一时间只能启用一个同用途的 Aily MCP 条目。 两个条目同时提供同一批工具会使工具路由产生歧义。切换时请遵循：先新建目标条目，验证 ping 与工具发现成功，最后再关闭旧条目。

5. 公网传输（默认 Cloudflare 命名隧道，回滚备用 ngrok）

主路径：Cloudflare 命名隧道 + 自有主机名。 在 Cloudflare 控制台完成以下一次性配置（不要在仓库或截图里放凭据、tunnel UUID 或证书 JSON）：

安装 cloudflared，并在你的终端完成 cloudflared tunnel login。
创建命名隧道：cloudflared tunnel create feishu-mcp（记下打印的 UUID）。
绑定主机名：cloudflared tunnel route dns feishu-mcp mcp.example.com（该子域需在Cloudflare DNS 中被代理）。
在 %USERPROFILE%\.cloudflared\config.yml 写外部连接配置，ingress 指向http://127.0.0.1:3000（以 .env 的 PORT 为准），并为证书 JSON 和 config.yml收紧 NTFS ACL。
保持手动启动：运行 scripts\start-cf-mcp.ps1，它会在当前会话启动 supervisor；不安装 Windows 服务，也不创建开机启动项。

把 PUBLIC_HOST 设置为这个自有主机名并重启本地启动器。随后运行有界健康验证（区分本地与公网失败，退出码非零即失败）：

.\scripts\test-cloudflare-tunnel.ps1 -PublicHost mcp.example.com -Port 3000 -MetricsPort 20241 -TunnelName feishu-mcp

手动会话状态与停止命令：

.\scripts\tunnel-supervisor.ps1 -Action Status
.\scripts\stop-cf-mcp.ps1

完整恢复说明见 docs/MANUAL_CLOUDFLARE_TUNNEL_RECOVERY.md。

回滚备用：ngrok。 观察期内如公网中断超过 5 分钟且原因未明，可按CLOUDFLARE_TUNNEL_MIGRATION.md 一键回滚：先运行 scripts\stop-cf-mcp.ps1，再在 .env 恢复 NGROK_DOMAIN 与 NGROK_AUTHTOKEN，运行 .\scripts\start-ngrok.ps1，并把 Aily endpoint 改回旧 ngrok 地址。不要把mcp.example.com 当作凭据，也不要把它复制给其他使用者。

测试环境（与正式环境隔离）

正式服务只使用 .env、127.0.0.1:3000 和 mcp.zxc66.asia。测试服务使用另一份.env.test、127.0.0.1:3001 和 mcp-test.zxc66.asia，其审批数据、任务、日志、工作区目录及 Cloudflare 凭据都必须独立。测试脚本不会读取、修改、重启或停止正式 MCP。

# 1. 复制 .env.test.example 为 .env.test，并只填写测试值
.\scripts\start-test-mcp.ps1

# 2. 如需公网测试，再使用独立的测试 Cloudflare 配置
.\scripts\start-test-cloudflared.ps1 -ConfigPath C:\test-cloudflared\config.yml

完成测试后停止测试进程即可。合并或发布代码是另一项独立操作；生产仍保持 .env 和3000 端口，除非你明确启动正式服务。

6. 在 Aily 添加 MCP

在 Aily 中添加企业自定义 MCP，Endpoint 类型选 Streamable HTTP。使用 Cloudflare时将 <你的公网主机名> 替换为 PUBLIC_HOST；使用 ngrok 时替换为自己的 ngrok 域名：

MCP endpoint: https://<你的公网主机名>/mcp
Authorization: Bearer <your-own-MCP_AUTH_TOKEN>
x-aily-user: <your-own-OWNER_USER_ID>

Authorization 和 x-aily-user 必须添加在请求头中。对于这个仅自己可用的个人MCP，Authorization 应使用固定值，其参数值为 Bearer <your-own-MCP_AUTH_TOKEN>，这样 Aily 才能在注册阶段发现完整工具清单。不要把真实 Token 放在展示名称、描述、图片或普通对话中；x-aily-user 应固定为你的 owner 身份。

保存新 MCP 后，先重新打开 Aily 对话并调用 ping 或让它枚举工具；确认成功后，再关闭旧的同用途 MCP 条目。出现 401 时，先核对 Token 是否与本机 .env 一致，以及是否包含Bearer 前缀。

Android 与 Windows 本地开发环境

项目内提供个人 MCP 接入教学 Skill。它适合让 Aily 或 Codex 先检查你的设备，再给出手动安装与接入步骤。

它会按项目需要检查：

Node.js、npm、Git、本地 MCP、ngrok；
Android Studio、Android SDK、JDK、Gradle wrapper、adb；
Visual Studio Build Tools、MSVC、Windows SDK、CMake。

它不会替你注册 ngrok、安装软件、填写 Token、修改 .env 或改变系统环境。示例提问：

检查我的 Windows 电脑是否能运行这个 MCP，并给我手动接入 Aily 的步骤。
检查这个 Android 项目缺少哪些 SDK、JDK 和 adb 配置，只给我手动修复方法。
检查这个 Windows 原生项目需要的 MSVC、Windows SDK 和 CMake 环境。

能力概览：42 个工具

工具清单由服务在 tools/list 中实际返回；Aily 的文字总结可能合并或漏列工具，应以该响应和 /health 为准。

分组	工具
连通与授权	`ping`、`auth`、`list_allowed_directories`
文件与目录	`read_file`、`write_file`、`edit_file`、`create_directory`、`list_directory`、`move_file`、`search_files`、`search_content`、`get_file_info`、`compare_files`、`apply_patch`
命令与 Git	`execute_command`、`git_status`、`git_diff`
结构化 Git	`git_workflow`（固定 Git 工作流 action）
网络与任务	`web_fetch`、`todo_write`、`todo_read`、`ask_user`
开发环境	`get_development_task`、`list_development_tasks`、`read_development_task_logs`、`cancel_development_task`、`inspect_development_environment`、`plan_environment_changes`、`apply_environment_plan`、`android_development`、`windows_development`、`node_development`、`python_development`、`java_development`、`manage_development_project`
本地工作流	`list_local_workspaces`（列出受保护目录中的工作空间和配方）、`run_local_workflow`（异步执行已登记的受控验证配方）
本地开发服务	`local_dev_server`（仅 owner；启动、查询日志或停止 catalog 声明的本机/LAN 开发服务；不接受任意命令，也不会自动通过 Cloudflare 公开）
工作区路由	`workspace_context`（owner 专用：选择/恢复受信任工作区，返回确定性的 `route.recommended`：Android 走 `android_development`、固定 Node 校验走 `run_local_workflow`，并提供 `error.nextAction`）
二进制制品	`manage_binary_artifact`
大文本传输	`manage_text_transfer`
Android 验证	`staging_android_verify`（按应用 Profile 执行受控的 SSH/ADB staging 验证）

manage_binary_artifact 用于验证、分块接收、存储和原子落盘 PNG、ZIP 等二进制制品；manage_text_transfer 用于超过单次 MCP 请求限制的 UTF-8 源码：先 begin（目标路径、字节数、SHA-256），再按返回的 48 KiB 上限调用 append，可用 inspect 查询断点，最后 commit 完成校验后的原子替换。小文件继续使用 edit_file；该工具只传输文本，绝不执行内容。它不提供任意二进制执行或解压能力。二进制构建产物通常应放在制品存储或 Release，而不是提交到 Git。

python_development 用于受控的 Python 版本检查、脚本运行和 pytest 验证。它会优先选择工作目录下的 .venv，再回退到系统 launcher，不接受任意 shell 字符串或原始 pytest flags。

构建与测试命令

结构化开发工具遵循 context-first 流程：workspace_context bootstrap/select → 阅读声明的指令文件 →workspace_context mark_instructions_read → 使用 git_workflow、java_development、node_development 或 python_development。Node 工具还提供固定的npm_ci、npm_test、npm_build、npm_lint、npm_typecheck action；Python 工具提供固定的python_version、script_run、pytest_run action；调用方不得用任意 shell 命令替代这些结构化 action。

execute_command 是本地 MCP 的通用命令工具；Aily 可能不会把任意 Shell 执行能力交给智能体。Node/PNPM 验证应优先使用结构化的 node_development：它要求已授权的workdir，且只允许 pnpm_version、test_run、build、typecheck 四个 action。Windows 上会以完全固定的 pnpm.cmd 命令片段启动包管理器；调用方仍不能传入任意命令或参数。两类工具都受目录边界、受保护内部目录、审批、超时、输出上限、取消、并发限制和审计约束。

在 Aily 中可这样请求：

请调用 node_development，action 为 typecheck，workdir 为已授权 Node 项目目录。
如果要做 Python 校验，请调用 python_development，action 为 pytest_run，workdir 为已授权 Python 项目目录。
如需审批，请在当前窗口展示审批卡；不要改用任意 shell 命令。

默认策略：

OWNER_COMMAND_POLICY=approval

个人设备所有者确实需要让构建和测试直通时，才可以显式配置：

OWNER_USER_ID=<your-own-owner-id>
OWNER_COMMAND_POLICY=direct

direct 仅跳过该 Owner 的普通单次命令审批；它不会放宽目录权限、内部数据保护、超时、输出限制、取消、审计或并发限制。非 Owner 仍遵循普通审批流程。包安装和构建脚本可能联网或产生外部副作用，不能视为可由回收站完全回滚的操作。

安全模型

传输鉴权：MCP_AUTH_TOKEN 保护公网 MCP 入口，错误或缺失会返回 401。
工具授权：支持 pin、header 和 none；公网 header 模式只能放在可信网关后。
目录白名单：仅允许 ALLOWED_DIRS 中的项目目录，解析后防止路径穿越和符号链接逃逸。
操作确认：文件写入、风险命令、敏感路径与首次网络来源按策略要求确认。
审计与限流：操作写入审计日志，Token 仅以哈希形式记录；并发、频率、大小和时间均有上限。
软删除：覆盖或移动文件会先进入项目的 .trash/；它不保证撤销网络、包管理器或外部系统副作用。

永远不要以管理员身份运行 MCP。不要把整个磁盘授权给日常 Aily 对话；优先只授权一个项目根目录。

常见问题

Aily 显示 401 或没有工具

检查顺序：本地 /health 是否正常、ngrok 是否在线、Aily endpoint 是否为 /mcp、Authorization 是否为固定请求头且值为 Bearer <your token>。Aily 的描述栏不会代替真实请求头值。

Aily 的文字回答只列出一部分工具

服务的 /health 与 tools/list 当前应返回 42 个工具。Aily 可能因平台安全策略只把其中一部分交给智能体；如果没有 execute_command，请使用 node_development 完成四个受限的 PNPM 操作；如果要验证 Python 脚本或 pytest，请使用 python_development，而不要要求智能体改用任意 Shell。

启动器报告公网 health 超时

在 Clash Fake-IP 等本机 DNS 场景可能发生。确认 http://127.0.0.1:3000/health 和 ngrok隧道状态；启动器不会因为该公网回访警告停止健康的本地服务。

Android 或 Windows 构建环境缺失

使用个人 MCP 接入教学 Skill 先检测，再按Android Studio SDK Manager 或 Visual Studio Installer 的手动步骤安装相应组件。

项目结构

feishu_mcp/
├── src/                         # MCP 服务、鉴权、工具和安全边界
├── scripts/                     # Windows 启动器与辅助脚本
├── skills/
│   └── personal-mcp-onboarding/ # 个人电脑接入教学 Skill
├── docs/                        # 设计、计划与接入参考
├── test/                        # Node 测试
├── .env.example                 # 本地配置模板，不含真实密钥
├── start-feishu-mcp.bat         # Windows 启动入口
└── SECURITY.md                  # 安全部署要求

开发与验证

npm install
npm run build
npm run typecheck

运行某一组测试时使用 Node 内置测试运行器，例如：

node --test test/launcher.test.mjs

完整配置项以 .env.example 和 src/config.ts 为准；详细 Aily 接入说明见docs/aily-integration-guide.md。

License

MIT

feishu_mcp：个人本地开发工作台 MCP