Astra Gemini
Provides tools for querying Git repository status, diffs, logs, and branches, plus applying unified diff patches with backup-based rollback.
Enables listing and running allowlisted npm scripts inside a registered project, with bounded output tailing.
Supports listing pnpm scripts and workspaces and running allowlisted pnpm scripts, optionally filtered to a workspace.
Allows running pytest test targets with keyword filtering and bounded output through the Python SDK.
Provides Python environment inspection, pytest execution, and compile checks, preferring a project-local virtualenv when available.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 拉快照、打补丁、跑白名单验证命令。
快速开始
克隆或解压本仓库到任意目录。
右键
install.ps1→ 使用 PowerShell 运行:检查 Node/Git、生成两个 Token 文件、运行完整测试套件、创建桌面快捷方式。双击桌面「Astra Gemini」(或目录内
Start-AstraGemini.vbs):托盘驻留并自动打开控制台http://127.0.0.1:3939/ui(仅本机可访问)。
安装目录下会生成两个 Token 文件(均已 gitignore):
文件 | 用途 |
| 客户端 Token: |
| 入网 Token:仅供子节点通过 |
控制台五个页签: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>/<项目>。
工具 | 作用 | 关键参数 | 关键返回 |
| 列出本机及全部在线子树项目 | 无 |
|
| 拉取过滤后的文本代码快照 |
|
|
| 校验、备份并应用 unified diff |
|
|
| 列出项目当前生效的 SDK |
|
|
| 在权限沙箱内执行异步 JS 验证脚本 |
|
|
补充说明:
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 | 函数 | 限制 |
|
| 只读查询 + 补丁备份回滚 |
|
| 仅 |
|
| 同上; |
|
| 优先使用项目内 |
|
| 仅允许访问 |
|
| 项目内只读,遵守 deny 规则 |
|
| 默认关闭;在 |
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(固定域名、低延迟)
VPS 安装 Node.js ≥ 25 与 Caddy,克隆本仓库到
/opt/astra-gemini。写
/etc/astra-gemini.env:HOST=127.0.0.1 PORT=3939 ASTRA_TOKEN=<客户端Token> ASTRA_JOIN_TOKEN=<入网Token> ASTRA_PUBLIC_URL=https://astra.example.comsudo cp deploy/astra-gemini.service /etc/systemd/system/ && sudo systemctl enable --now astra-gemini。deploy/Caddyfile改为你的域名放入 Caddy(reverse_proxy 127.0.0.1:3939,WebSocket 自动透传),sudo systemctl reload caddy。控制台访问:本机
ssh -L 3939:127.0.0.1:3939 user@vps,浏览器开http://127.0.0.1:3939/ui(管理面只认 localhost)。
方案 B:Cloudflare 命名隧道(免 VPS)
Cloudflare Zero Trust → Networks → Tunnels 新建隧道并绑定固定域名,取得 Tunnel Token。
控制台隧道区选「命名隧道」,填入 Token 与固定域名(
https://xxx.example.com)保存后启动(Token 经环境变量传入,不出现在命令行参数)。该固定域名自动成为 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)——牵线服务只撮合连接与转发密文,没有任何调用权限。
部署牵线服务(任选一台有公网地址的机器,含 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 }——中继只统计转发字节数,不解析内容。两端都配置牵线服务:控制台「远程直达」卡片填入同一服务地址(
wss://rv.example.com)与 RV_TOKEN。节点上线时用identity.json的 Ed25519 私钥对服务下发的 challenge 签名,服务由此推导出ag1-节点地址。A 上给 B 起别名:在「远端别名」填入 B 的节点地址(B 控制台「本机节点地址」一键复制
ag1-…)。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>"通道建立:发起后双方并发拨对方的候选地址——P2P 监听的非回环 IPv4、非 link-local IPv6(含 ULA)、UPnP 映射的公网地址——约 2 秒直连窗口内最先完成 mutual TLS 的 socket 胜出(
mode: "direct");否则经牵线服务建 WebSocket 管道,在同一密管上再跑同一套 TLS(mode: "relay")。B 端remoteAllowFrom非空时,不在名单内的发起地址会被拒绝。暂未实现 UDP hole punching:双方都在 NAT 后且无 IPv6/UPnP 时只能走中继。
/remote/...入口与管理控制台同样只接受本机 socket。
本地状态文件
均位于桥接器安装目录,全部已加入 .gitignore,勿提交:
文件/目录 | 内容 |
|
|
| 项目注册表(见上文) |
| 客户端 Token / 入网 Token |
| 子节点 TOFU 绑定( |
| OAuth 客户端与令牌哈希(不存明文令牌) |
| Ed25519 节点密钥对( |
|
|
|
|
开发与测试
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Verified component catalog over remote MCP: agents pick ids and get a project that builds.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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.18PolyForm Noncommercial 1.0.0
- AlicenseBqualityDmaintenanceEnables any MCP client to read, search, patch, and execute commands in a codebase, including interactive sessions and git operations, with permission modes and safety boundaries.18Apache 2.0
- FlicenseBqualityDmaintenanceEnables secure, policy-controlled operations on local git repositories through MCP, including bounded reads, context-checked patches, allowlisted tasks, and guarded git operations.10-
- AlicenseAqualityBmaintenanceEnables MCP-compatible AI clients to securely access explicitly authorized local project files and run approved development commands with bounded execution and audit logging.1MIT