Skip to main content
Glama
deenesjakoruzh
aditya1503

LocalForge

by aditya1503
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

LocalForge ⚒️

混合智能体式编码（Hybrid Agentic Coding）下的模型上下文协议（MCP）桥——将 token 密集型的实现工作委托给本地开源模型。
在云端架构设计，在本地落地实现，节省 80–90% 的高级 API token。

MCP Compatible License: MIT Node.js Built by ADIS

💡 问题与解决方案

在传统的代理式编码方案中，前沿模型（OpenAI Codex、Claude 3.7 Sonnet / Opus 等）执行工作流的每一个步骤——高层推理、读取仓库中成千上万行代码、运行测试套件、修复编译错误，概莫能外。

这极其昂贵且低效：

  • 超过 80% 的 token 总量消耗在重复、机械的循环中（文件发现、语法修复、单元测试迭代）。

  • 专有代码库上下文被反复流式传输到外部云 API。

LocalForge 通过混合代理式编码来化解这一困境：

  1. 前沿模型（云端）：担任架构师与评审者（高智能，低 token 用量）。

  2. LocalForge（MCP 边界）：分发结构化且有边界约束的任务规格，并管理本地沙箱。

  3. 本地开源模型（本地 LLM）：在本地完成高 token 消耗的实现、编辑与测试调试循环，边际 API 成本为零。

  4. 前沿评审：云端模型仅检查精炼过的 diff、日志与摘要以验证正确性。

   ┌──────────────────────────────────────────────────────────┐
   │                  1. ARCHITECT / REVIEWER                 │
   │                      (Codex / Claude)                    │
   │       • Understands requirement  • Reviews diff & logs   │
   └────────────────────────────┬─────────────────────────────┘
                                │
                    [MCP Task Specification]
                                │
                                ▼
   ┌──────────────────────────────────────────────────────────┐
   │                   2. LOCALFORGE (MCP)                    │
   │      • Session continuity      • Privacy boundary        │
   │      • Cross-process locks     • Telemetry ledger        │
   └────────────────────────────┬─────────────────────────────┘
                                │
                    [Local Inference Stream]
                                │
                                ▼
   ┌──────────────────────────────────────────────────────────┐
   │                3. IMPLEMENTATION WORKER                  │
   │           (DeepSeek V4 Flash / Qwen 2.5 / 3.5)           │
   │  ┌────────────────────────────────────────────────────┐  │
   │  │ 🔄 LOCAL ITERATION LOOP                            │  │
   │  │ Read Repo ➔ Edit Code ➔ Run Tests ➔ Fix Errors    │  │
   │  └────────────────────────────────────────────────────┘  │
   └──────────────────────────────────────────────────────────┘

Related MCP server: local-agent

✨ 核心特性

  • 📉 减少 80–90% 高级 token：把 token 密集型的代码编辑、文件索引和测试调试完全放在本地硬件上。

  • 🛡️ 严格的隐私与安全边界：敏感的内部文件与多轮诊断转储都停留在本地网络内。

  • 🔄 会话连续性：多轮后续操作（opencode_followup）续接同一执行会话，而无需重新发送整个仓库上下文。

  • 🔒 跨进程仓库锁：防止多个智能体标签页或客户端之间破坏性并发的写入。

  • 📊 遥测与审计台账：自动将执行时长、受动文件、新增/删除行数以及预估 token 节省量记录至 state/ledger.jsonl。

  • ⚡ 零配置客户端注册：一条命令即可完成 Codex、Claude Code、Claude Desktop、Antigravity 的接入。

🛠️ MCP 工具参考

LocalForge 通过标准 Model Context Protocol (stdio/JSON-RPC) 注册了 8 个原生工具：

工具

说明

opencode_implement

将一份有界任务规格（目标、约束、接口、上下文）分发给本地 worker。

opencode_wait

单次阻塞等待，相当于每次运行中任务达到终态（completed / failed），从而替代轮询状态。

opencode_status

对运行中或已结束任务提供一个非阻塞的状态快照。

opencode_diff

返回本地 worker 相对基线提交之所做改动，范围收敛的 git diff。

opencode_followup

继续使用已创建的 OpenCode 会话，按评审结论修复缺陷、补充边界场景或增加测试。

opencode_cancel

优雅终止正在运行的任务及其子进程。

opencode_health

检查本地推理端点、opencode CLI 与正在生效的模型配置是否健康。

opencode_history

查询给定仓库过去的委派结果、执行耗时及成功率。

🚀 快速开始

1. 前置条件

  • Node.js：>= 20.0.0

  • OpenCode CLI：已安装并可通过 PATH 访问（使用 npm i -g opencode-ai 或二进制安装包）。

  • 本地推理模型：一个运行中的、与 OpenAI 兼容的本地推理端点（例如 DeepSeek V4 Flash、Qwen 2.5/3.5，可依托 vLLM、Ollama、SGLang 或双节点 DGX Spark 集群提供服务）。

2. 安装与构建

git clone https://github.com/aditya1503/LocalForge.git
cd LocalForge
npm install
npm run build

3. 验证健康状态

npm run dev
# or run health check
tsx tests/v2.test.ts

4. 连接你的 AI 客户端

LocalForge 内收一个单命令的客户端自动写入器：

# Register with OpenAI Codex / Antigravity
node scripts/register-client.mjs antigravity

# Register with Claude Code
node scripts/register-client.mjs claude-code

# Register with Claude Desktop
node scripts/register-client.mjs claude-desktop

⚙️ 配置

请在环境变量或客户端配置中设置以下参数：

变量

默认值

说明

OPENCODE_MODEL

spark/deepseek-v4-flash-0731

传递给 OpenCode 的模型标识符。

WORKER_HEALTH_URL

http://127.0.0.1:8890/v1/models

本地推理服务器的健康检查端点。

ALLOWED_REPO_ROOT

当前工作目录

根目录白名单，用于防止路径穿越。

TASK_TIMEOUT_MS

600000（10 分钟）

超过此时间后该任务将被自动终止。

📊 遥测与报告

每个已结束的任务都会自动把遥测数据写入 state/ledger.jsonl。运行内置的统筹工具可根据数据负载分析节省情况：

npm run rollup

示例输出示例：

=== LocalForge Telemetry Rollup ===
Total Tasks: 42
Success Rate: 95.2%
Avg Task Duration: 28.4s
Estimated Cloud Tokens Saved: ~1.85M tokens
Top Task Classes: unit-test-generation, bugfix, refactoring

🎨 交互式架构信息图

此仓库附带一个独立的交互式 HTML 架构信息图，直观展示完整的 MCP 委托链路：

open index.html

📄 许可证

MIT 许可证。由 ADIS 基于 “人工开发智能服务”（Artificially Developed Intelligence Services）设计并持续维护。

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • local-llm-delegation-mcp

    mrrodriguez
    A
    license
    A
    quality
    D
    maintenance
    Optimizes token costs by intelligently delegating low-complexity tasks to local LLMs via LiteLLM, enabling cost-effective development workflows.
    3
    1
    MIT