Skip to main content
Glama

Astra Gemini(星空双子座)v0.1.0

零外部依赖(仅 Node.js 标准库)的本地 MCP 桥接器:让网页端或 CLI 的 AI 通过 MCP 协议读取本机项目代码、应用 unified diff 补丁、在权限沙箱中跑验证脚本。支持增量哈希去重同步、补丁完整性校验与乐观锁、传输自动 gzip 压缩,以及多机树状组网(优先点对点直连、失败自动回退中继)。

需要 Node.js ≥ 25:exec_verify 脚本在 node --permission 权限模型沙箱中运行,Node 25 起该模型才支持网络限制(--allow-net),更早版本无法保证沙箱断网,因此整体要求 ≥ 25。

典型场景:把一台或多台机器上的代码仓库暴露给 Claude.ai、ChatGPT 或其他 MCP 客户端——AI 拉快照、打补丁、跑白名单验证命令。

快速开始

  1. 克隆或解压本仓库到任意目录。

  2. 右键 install.ps1 → 使用 PowerShell 运行:检查 Node/Git、生成两个 Token 文件、运行完整测试套件、创建桌面快捷方式。

  3. 双击桌面「Astra Gemini」(或目录内 Start-AstraGemini.vbs):托盘驻留并自动打开控制台 http://127.0.0.1:3939/ui(仅本机可访问)。

安装目录下会生成两个 Token 文件(均已 gitignore):

文件

用途

token.txt

客户端 Token:/mcp 的 Bearer 凭据,同时是 OAuth 授权页的登录口令

join-token.txt

入网 Token:仅供子节点通过 wss://…/ws/tree 挂载到本节点

控制台五个页签:SDK 能力开关 / 本地项目 / 星图组网 / 备份回滚 / 自检与日志。托盘菜单可复制本机 MCP 地址、客户端 Token、入网 Token。

也可不用托盘直接启动:HOST=127.0.0.1 PORT=3939 AUTH_MODE=bearer ASTRA_TOKEN=… ASTRA_JOIN_TOKEN=… node src/server.mjs(AUTH_MODE=none 完全免鉴权,仅限本机测试)。

Related MCP server: Coding Tools MCP

MCP 接口与工具

  • POST /mcp:JSON-RPC 2.0,单请求单响应(无 SSE)。认证为 Authorization: Bearer <客户端 Token> 或 OAuth access token;未带凭据返回 401 并附 WWW-Authenticate: Bearer resource_metadata=…。

  • WS /ws/tree:子节点入网(仅入网 Token)。WS /ws/direct:节点间点对点直连(15 秒一次性票据)。GET /health:存活探测。

  • 项目寻址支持多级路径:本机项目写 my-app,子树项目写 <节点Id>/<项目>,更深层写 <a>/<b>/<项目>。

工具

作用

关键参数

关键返回

list_projects

列出本机及全部在线子树项目

无

project, mode, sdks, allowedScripts, exists, description

pull_snapshot

拉取过滤后的文本代码快照

project*、paths[](glob 过滤)、knownHashes(去重)、includeContent(默认 true)、maxFiles(默认 200)、maxTotalBytes(默认 2000000)

files[{path,bytes,sha256,content}]、unchangedPaths、deleted、skipped、bundleSha256、truncated

apply_patch

校验、备份并应用 unified diff

project*、patch*、patchSha256、expectedHashes、dryRun

backupId、patchSha256、files、postHashes

list_sdks

列出项目当前生效的 SDK

project*

sdks[{name,title,description,functions}]

exec_verify

在权限沙箱内执行异步 JS 验证脚本

project*、script*、timeoutMs(1s–120s,默认 30s)、maxOutputBytes(默认 8192)

ok、result、logs、durationMs、truncated

补充说明:

  • pull_snapshot 的 knownHashes 传 {相对路径: sha256或md5}:哈希一致的文件只进 unchangedPaths 不重传内容;已消失的文件列入 deleted;bundleSha256 是全部纳入清单文件的确定性指纹。文件枚举优先走 git 清单,非 git 目录回退目录遍历,全程套用 deny 规则。

  • apply_patch 流程:可选校验 patchSha256(SHA-256 或 MD5,防传输截断)→ expectedHashes 乐观锁(值为 null 表示该文件必须不存在;32 位十六进制按 MD5、否则按 SHA-256 比对现网文件)→ git apply --check → 自动备份触及文件到 .bridge-backup/<项目>/<backupId> → git apply。成功后返回 postHashes(SHA-256,null 表示文件已删)可直接刷新缓存。补丁以 git -c core.autocrlf=false apply 应用,LF 内容逐字节落盘。dryRun: true 只校验不写入。

  • exec_verify 在独立的 node --permission 子进程中执行:仅被授予读自身文件权限,无网络、写盘、子进程、Worker、原生扩展权限。脚本内仅暴露 sdk 命名空间、受限 console 与定时器;所有 sdk.* 调用跨 IPC 边界、返回 Promise,必须 await。示例:

    const br = await sdk.git.branches();
    const t = await sdk.npm.run("test");
    return { branch: br.current, testsOk: t.ok };

内置 SDK

SDK

函数

限制

git

status、diff({statOnly,maxChars})、log(limit≤30)、branches、rollback(backupId)

只读查询 + 补丁备份回滚

npm

listScripts、run(scriptName,{tailLines≤120})

仅 allowedScripts 白名单脚本(默认 test/lint/typecheck/check/build/verify)

pnpm

listScripts、listWorkspaces、run(scriptName,{filter,tailLines})

同上;filter 仅允许 ^[a-zA-Z0-9@/_.*-]+$

python

info、pytest(target,{keyword,tailLines})、compileCheck(target)

优先使用项目内 .venv/venv 解释器

http

probePort(port,timeoutMs≤5000)、request(url,{method,headers,body,maxChars})

仅允许访问 127.0.0.1/localhost/::1

fs_read

stat、tail(relPath,lines≤200)、grep(pattern,subdir,maxMatches≤40)

项目内只读,遵守 deny 规则

worktree

list、create(name,ref)、remove(name)

默认关闭;在 .bridge-worktrees/<项目>/<name> 建隔离工作树,名称限 ^[a-zA-Z0-9_-]{1,48}$

SDK 生效 = 全局开关(settings.globalSdkEnabled,控制台页签热生效)∩ 项目 sdks 白名单("*" 表示全部全局启用的 SDK)。SDK 目录:sdks/global/*.mjs 全局生效,sdks/projects/<项目别名>/*.mjs 仅对该项目生效;新文件丢入后经 list_sdks / 控制台刷新即被发现。

projects.json

{
  "my-app": {
    "root": "C:\\path\\to\\my-app",
    "mode": "direct",
    "sdks": ["git", "pnpm", "npm", "http", "fs_read"],
    "allowedScripts": ["test", "lint", "build"],
    "deny": ["docs/private/**"],
    "description": "备注"
  }
}
  • 项目别名:^[a-zA-Z0-9_-]{1,64}$;root 必填且必须已存在。

  • mode:direct(默认,允许打补丁)或 readonly(拒绝 apply_patch)。

  • sdks:缺省为 ["git","pnpm","npm","python","http","fs_read"](不含 worktree);"*" 表示全部全局启用的 SDK。

  • allowedScripts:缺省为内置白名单 test/lint/typecheck/check/build/verify。

  • deny:追加屏蔽规则。默认 deny 不可关闭,对所有文件读取/快照/补丁生效:.env*、**/*.pem|key|p12|pfx、**/*secret*、**/id_rsa*|id_ed25519*、.git/**、node_modules/**、.bridge-backup/**。

  • 也可在控制台「本地项目」页签可视化编辑。

安全模型

  • 两类凭据权限边界:客户端 Token → /mcp 全部工具 + OAuth 登录口令;入网 Token → 仅 /ws/tree 注册。两者互不相通(交叉使用均 401),比较均使用恒定时算法。

  • 重要:拿到客户端 Token(或完成 OAuth 授权)的调用方,对每个 mode: "direct" 项目约等于拥有本机用户的代码执行能力——可先 apply_patch 修改 package.json,再 exec_verify 调 sdk.npm.run 执行。只给受信任的 AI/节点授权。

  • readonly 仅阻止 apply_patch 写盘,不阻止 exec_verify(其后果取决于启用的 SDK,如 npm run build 仍会写产物)。需要严格只读时,请同时把项目 sdks 收缩为 ["fs_read"] 等纯读集合。

  • 上级节点的 /mcp 凭据持有者可对整棵子树(含全部后代节点的项目)发起工具调用;入网 Token 只决定谁能挂载上来,不约束上级的调用能力。

  • exec_verify 沙箱边界:独立 node --permission 子进程,仅 --allow-fs-read 自身文件;SDK 调用经宿主端白名单校验的 IPC 代理,返回值 JSON 序列化。已知残余风险:process.kill/process.abort 不受权限模型管控(脚本可终止自身或信号同用户进程);CPU/内存仅靠超时兜底(默认 30s、上限 120s)。

  • 管理控制台(/ui、/api/*)只接受本机 socket,且校验 Host(仅 127.0.0.1/localhost/::1)、Origin 必须同源、拒绝 Sec-Fetch-Site: cross-site(防 DNS rebinding 与跨站提交)。经公网入口到达的管理请求一律 403。

  • OAuth 防护:强制 PKCE S256;授权码 60 秒一次性;refresh token 轮换(旧值立即失效);access token 1 小时、refresh token 30 天;授权口令 10 分钟内失败超 10 次锁定 10 分钟;/oauth/register 限流(默认每小时 20 次、客户端上限 200,超限时优先驱逐无活跃令牌的客户端)。

  • 节点 TOFU 绑定:子节点首次注册将 nodeId → sha256(nodeSecret) 落盘 nodes.json;此后同名不同密的连接被 1008 拒绝且不顶替现有连接,控制台「星图组网」可一键移除重置。

  • 直连票据 15 秒一次性单用;心跳每 25 秒一次、超过 75 秒无应答断开并自动重连(退避重试,成功即重置)。

  • 远程直达信任边界:P2P 监听端口(默认 3940)的入站 socket 必须在 5 秒内发送带已知会话 ID 的 ASTRA-P2P/1 <sid> 前导行,未知 sid 立即断开,对扫描器不暴露 TLS;随后建立 TLS 1.3 双向认证并把对端证书 SPKI 锁定到 ag1- 节点地址(identity.json 中的 Ed25519 密钥决定地址)。

  • 牵线服务无法冒充任一节点(hello 帧用节点私钥对 challenge 签名)也读不到通道明文,但能看到元数据:谁连谁、双方 IP、转发字节数。remoteAllowFrom 非空时可再收一层呼入白名单。

  • UPnP 默认开启,会在路由器上映射 P2P 端口(TCP,租约 3600 秒,退出时自动删除映射);不需要时在设置里关闭。

上公网

publicUrl(设置项或 ASTRA_PUBLIC_URL)决定 OAuth issuer 与对外 MCP 地址,生产环境务必显式配置;未配置时按请求 Host + x-forwarded-proto/cf-ray 推断并记日志提醒。注意不同入口下项目路径前缀不同:经 VPS 父节点访问家中电脑项目写 home/my-app,直连家中电脑自己的入口写 my-app。

方案 A:Linux VPS + Caddy(固定域名、低延迟)

  1. VPS 安装 Node.js ≥ 25 与 Caddy,克隆本仓库到 /opt/astra-gemini。

  2. 写 /etc/astra-gemini.env:

    HOST=127.0.0.1
    PORT=3939
    ASTRA_TOKEN=<客户端Token>
    ASTRA_JOIN_TOKEN=<入网Token>
    ASTRA_PUBLIC_URL=https://astra.example.com
  3. sudo cp deploy/astra-gemini.service /etc/systemd/system/ && sudo systemctl enable --now astra-gemini。

  4. deploy/Caddyfile 改为你的域名放入 Caddy(reverse_proxy 127.0.0.1:3939,WebSocket 自动透传),sudo systemctl reload caddy。

  5. 控制台访问:本机 ssh -L 3939:127.0.0.1:3939 user@vps,浏览器开 http://127.0.0.1:3939/ui(管理面只认 localhost)。

方案 B:Cloudflare 命名隧道(免 VPS)

  1. Cloudflare Zero Trust → Networks → Tunnels 新建隧道并绑定固定域名,取得 Tunnel Token。

  2. 控制台隧道区选「命名隧道」,填入 Token 与固定域名(https://xxx.example.com)保存后启动(Token 经环境变量传入,不出现在命令行参数)。

  3. 该固定域名自动成为 OAuth issuer 与公网 MCP 地址。注意 Cloudflare 单条 HTTP 请求约 100 秒即被切断,timeoutMs 超过 ~90 秒的 exec_verify 请走 VPS 或局域网直连。

另有「临时隧道」模式(随机 *.trycloudflare.com 域名)适合临时演示;随机域名下 OAuth issuer 每次重启都会变化,不建议用于正式接入。

连接网页 AI 客户端(Claude.ai / ChatGPT)

MCP 地址填 <公网地址>/mcp,认证方式选 OAuth:跳出的中文授权页输入客户端 Token(token.txt)即完成授权(DCR 自动注册 + PKCE S256 + 授权码 + refresh token 轮换)。

子节点入网

子节点控制台「上游父节点」填 wss://<公网地址>/ws/tree + 入网 Token(join-token.txt),保存即自动连入并出现在父节点「星图组网」页签。协议版本不匹配、nodeSecret 不匹配等策略性关闭(1008)不会自动重连,修正后需重新保存上游;被父节点「移除/重置」(1000)则会自动重连并以全新绑定重新注册。

远程直达(A 上的 Claude Code 访问 B)

A、B 是两台各自运行 astra-gemini 的机器。A 本机的 AI 客户端连 http://127.0.0.1:<A端口>/remote/<B别名或地址>/mcp,请求经端到端加密通道(TLS 1.3 mutual + 节点证书固定)直达 B 的 /mcp 入口,授权只看 B 入口自己的凭据(B 的客户端 Token 或 OAuth)——牵线服务只撮合连接与转发密文,没有任何调用权限。

  1. 部署牵线服务(任选一台有公网地址的机器,含 A/B 之外的 VPS):

    RV_TOKEN=<随机长令牌> HOST=127.0.0.1 PORT=3941 npm run rendezvous

    生产环境用 deploy/astra-rendezvous.service(环境文件 /etc/astra-rendezvous.env 写入 RV_TOKEN、HOST=127.0.0.1、PORT=3941)加 Caddy 反代一个独立域名(deploy/Caddyfile 有示例)。GET /health 返回 { ok, nodes, sessions, relayedBytes }——中继只统计转发字节数,不解析内容。

  2. 两端都配置牵线服务:控制台「远程直达」卡片填入同一服务地址(wss://rv.example.com)与 RV_TOKEN。节点上线时用 identity.json 的 Ed25519 私钥对服务下发的 challenge 签名,服务由此推导出 ag1- 节点地址。

  3. A 上给 B 起别名:在「远端别名」填入 B 的节点地址(B 控制台「本机节点地址」一键复制 ag1-…)。

  4. A 上给 AI 配接入(以别名 home-b 为例,控制台可直接复制该行):

    claude mcp add --transport http home-b http://127.0.0.1:3939/remote/home-b/mcp --header "Authorization: Bearer <B 的客户端 Token>"
  5. 通道建立:发起后双方并发拨对方的候选地址——P2P 监听的非回环 IPv4、非 link-local IPv6(含 ULA)、UPnP 映射的公网地址——约 2 秒直连窗口内最先完成 mutual TLS 的 socket 胜出(mode: "direct");否则经牵线服务建 WebSocket 管道,在同一密管上再跑同一套 TLS(mode: "relay")。B 端 remoteAllowFrom 非空时,不在名单内的发起地址会被拒绝。

  6. 暂未实现 UDP hole punching:双方都在 NAT 后且无 IPv6/UPnP 时只能走中继。/remote/... 入口与管理控制台同样只接受本机 socket。

本地状态文件

均位于桥接器安装目录,全部已加入 .gitignore,勿提交:

文件/目录

内容

settings.json

nodeId、nodeSecret、上游/隧道 Token、publicUrl、SDK 与直连开关(含敏感信息)

projects.json

项目注册表(见上文)

token.txt / join-token.txt

客户端 Token / 入网 Token

nodes.json

子节点 TOFU 绑定(nodeId → sha256(nodeSecret))

oauth-state.json

OAuth 客户端与令牌哈希(不存明文令牌)

identity.json

Ed25519 节点密钥对(ag1- 地址的来源;私钥泄露=节点身份被冒充)

.bridge-backup/

apply_patch 自动备份,供回滚

.bridge-worktrees/

worktree SDK 创建的隔离工作树

开发与测试

npm test(即 node --test test/bridge.test.mjs,node:test 零依赖)覆盖:单节点工具链与项目防火墙、快照去重与补丁完整性/gzip、沙箱逃逸防护、直连升级与中继回退、Token 隔离、TOFU 劫持与重置、OAuth 全流程、心跳重连、跨节点超时。

开发控制台

控制台源码在 web/(Vite + React + TypeScript + Tailwind + shadcn/ui),构建产物即 src/ui.html。

# 先启动一个开发用服务端(控制台通过它代理 /api 与 /remote)
$env:HOST="127.0.0.1"; $env:PORT="3940"; $env:AUTH_MODE="none"; node src/server.mjs

# 另开终端:安装依赖并启动前端开发服务器
cd web
npm install
npm run dev

改动后运行 cd web && npm run build(先 typecheck 再打包)重新生成 src/ui.html。src/ui.html 是随仓库提交的运行产物,终端用户无需构建前端。开发服务器只绑定 127.0.0.1,不要用 --host 对外暴露(代理会剥离 Origin/Sec-Fetch-Site 校验头,暴露即失去该防护)。

许可证

Apache License 2.0,详见 LICENSE 与 NOTICE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to safely access user-local filesystems, apply validated patches, inspect git state, and run persistent jobs on outbound-connected local runners through a stateless Cloudflare control plane.
      18
      PolyForm Noncommercial 1.0.0
    • F
      license
      B
      quality
      D
      maintenance
      Enables secure, policy-controlled operations on local git repositories through MCP, including bounded reads, context-checked patches, allowlisted tasks, and guarded git operations.
      10
      -