Folderforge

FolderForge turns any local folder into a safe, full-tool MCP workspace for AI agents.

Installation

FolderForge is a single CLI (folderforge) that an AI coding agent launches over stdio. It needs Node.js >= 22. It runs against any project folder you point it at with --project; a config file is optional (without one it allows just that project directory and applies safe defaults).

Option 1 - npx (no install, recommended)

The fastest path: let your agent run FolderForge on demand. Nothing to install globally. Point any MCP client at it:

{
  "mcpServers": {
    "folderforge": {
      "command": "npx",
      "args": ["-y", "@musashishao/folderforge", "--stdio", "--project", "/absolute/path/to/your-project"]
    }
  }
}

Try it in a terminal first:

npx -y @musashishao/folderforge --project . --stdio

Option 2 - global install from npm

Install once, then call folderforge from anywhere:

npm install -g @musashishao/folderforge
folderforge --version

# run against any folder
cd /path/to/your-project
folderforge --stdio --project .

Agent config when installed globally:

{
  "mcpServers": {
    "folderforge": {
      "command": "folderforge",
      "args": ["--stdio", "--project", "/absolute/path/to/your-project"]
    }
  }
}

Option 3 - from source (Git, for contributors)

Clone and build when you want to hack on FolderForge or run an unreleased version:

git clone https://github.com/roronoazoroshao369/FolderForge.git
cd FolderForge
npm install
npm run build        # emits dist/

# optional: expose the `folderforge` command system-wide
npm link

# or run directly without linking
node dist/main.js --stdio --project /path/to/your-project

During development you can skip the build step and run the TypeScript source directly:

npm run dev -- --stdio --project /path/to/your-project

You can also install straight from a Git remote without a published npm release:

npm install -g github:roronoazoroshao369/FolderForge

Pointing at a different folder

The folder FolderForge serves is independent of where it is installed. Set the working project with --project (and, if you use a config file, make sure its workspace.allowedDirectories includes that folder). To work across several projects at once, list them all in allowedDirectories.

Limiting the tool surface (tool list caps)

Some MCP clients cap how many tools they will load (around 50). FolderForge exposes a large native catalog, so you can trim the advertised list at startup to a focused set. The filter is applied before the first tools/list, so the client never sees the tools you excluded. Most presets retain the workspace group; vibe-lite is intentionally folder-scoped and is the exception.

Fastest path - the vibe preset (workspace, workflow, agent, file, search, terminal, process, git, code, build):

{
  "mcpServers": {
    "folderforge": {
      "command": "npx",
      "args": ["-y", "@musashishao/folderforge", "--stdio", "--project", "/path/to/project", "--tools-preset", "vibe"]
    }
  }
}

Other ways to control it (CLI flags override the config file):

# Pick whole groups
folderforge --stdio --project . --tools-groups file,search,terminal,git,code,build

# Start from a preset, then fine-tune
folderforge --stdio --project . --tools-preset vibe --tools-disable search_ast --tools-enable run_test

Available presets: vibe (71-tool coding/workflow surface in the audited tree), vibe-lite (folder-scoped coding plus all browser wrappers, hard-capped at 50), readonly (42-tool exploration-oriented surface), and full (269 native tools before dynamic child/plugin tools). Groups include workspace, workflow, agent, file, search, terminal, process, git, build, code, pkg, format, coverage, memory, security, browser, db, plugin, and game.

Or set it in folderforge.yaml so you don't repeat flags:

tools:
  preset: vibe
  # enabledGroups: [file, search, git, code, terminal]
  # enabled: [run_test]
  # disabled: [search_ast]

What it does

• Activates a local workspace (single or multiple projects at once)
• Exposes MCP tools over stdio and localhost HTTP
• Enforces path, command, and secret policy with a four-level risk model
• Gates sensitive actions behind an approval queue (persisted across restarts)
• Records every call to an append-only audit log
• Supports file, search, shell, process, git, build, code-intelligence, memory, browser, and database workflows

Status (2.1.0 prepared for release)

npm latest currently resolves to stable 2.0.0. The repository now targets 2.1.0, adding OAuth 2.1/OIDC resource-server support for ChatGPT, a hardened agent/admin authorization boundary, and the Auth0 one-command connector. The complete local release gate passes 397 tests across 50 files, both dependency audits, build, 102-file packed-tarball installation, OAuth package startup, stdio MCP, and authenticated HTTP MCP smoke. The connector changes are verified locally but remain uncommitted; no 2.1.0 npm publication, Git tag, or hosted release is implied here. The audited native registry contains 269 tools; the vibe, vibe-lite, readonly, and full presets advertise 71, 50, 42, and 269 native tools respectively before dynamic child/plugin additions.

• Core and governance - multi-project activation, path/command/secret policy, exact once/session approvals, rate limits, append-only audit, and governed workflows.
• MCP - stdio and authenticated Streamable HTTP, structured error evidence, progress, cancellation, elicitation, image/resource/resource-link delivery, child facades, and dynamic plugin adapters.
• AI/browser runtime - bounded code context, transactional edits, verification/report tools, and stable responsive browser wrappers.
• Release gates - typecheck, lint, 397 unit/integration tests, build, both dependency audits, npm pack, temporary tarball install, CLI/stdio smoke, live authenticated HTTP MCP initialize/list/call smoke, and six-entry cross-platform CI validation for the previously committed base. The new connector has been validated locally on Linux; its cross-platform CI run remains a release action.
• Trust boundary - local plugin packages receive a tamper-detection SHA-256 tree digest and environment allowlisting, but permission declarations remain review/audit metadata rather than an OS sandbox. The digest is not publisher identity or signed provenance; untrusted distribution remains disabled.

See docs/roadmap.md, docs/releasing.md, docs/compatibility.md, and docs/migration-2.0.md for the release record, gates, compatibility contract, and migration notes.

MCP protocol features (1.2)

Beyond tools/list / tools/call, FolderForge supports progress notifications (P4), cancellation (P6), and elicitation (P8), wired through a per-call control object that leaves the frozen tool schema untouched.

Approval administration boundary

When a tool is gated by the approval queue (for example git_commit, git_push, or file_delete), the agent receives an approvalId and cannot resolve it over the MCP tool plane. Approval resolution is restricted to the dashboard admin plane (http://localhost:7332 → Approvals).

Each request records the requester principal and an expiry. A distinct admin principal may grant once (exact requester + tool + canonical arguments, consumed once) or session (requester + tool for the current process). Self-approval, expired approvals, argument replay, and approval reuse by another principal are rejected. Runtime policy changes, including elevation to danger, are also admin-plane operations; the agent-facing registry does not advertise them.

Embedded resources

Tool results can now carry MCP content blocks beyond plain text. git_diff attaches the diff as an embedded text/x-diff resource, and child MCP image blocks are promoted so browser_screenshot can render directly in vision-capable clients. Other tools may attach resource_link blocks pointing to local file URIs or dashboard URLs. Promoted image base64 is not duplicated in the compatibility text summary.

git_reset, git_push, and git_pull confirm interactively before acting when the client supports elicitation, and git_push / git_fetch / git_pull / process_tail emit progress notifications.

Run

The default transport is stdio (for agents). You can also serve over HTTP on a port.

From source (dev)

npm install
npm run dev -- --stdio

or over HTTP:

npm run dev -- --http --port 7331 --host 127.0.0.1

Via npx (no install)

stdio:

npx -y @musashishao/folderforge --project . --stdio

HTTP with an API key and a trimmed tool surface - this is a complete, copy-pasteable example:

npx -y @musashishao/folderforge --project . --http --port 17331 \
  --api-key "key" --tools-preset vibe-lite

What that command does:

• serves MCP over HTTP on http://127.0.0.1:17331/mcp (default host is loopback);
• sets one API key (key), which turns auth on - every request must send it, even on localhost;
• limits the advertised tools to the vibe-lite preset (capped at 50).

Call it from a client:

curl -sS -X POST http://127.0.0.1:17331/mcp \
  -H "X-API-Key: key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

CLI commands

Command	Description
folderforge doctor [--json]	Run read-only installation, configuration, dependency, port, plugin, and state diagnostics
folderforge setup browser [--with-deps]	Explicitly install package-compatible Playwright Chromium; may access the network
folderforge setup browser --dry-run --json	Resolve the exact package-local setup command without downloading anything
folderforge connect chatgpt [--quick|--secure]	Provision/reuse Auth0 OAuth resources, start MCP connectivity, verify metadata, and print the ChatGPT URL
folderforge chatgpt status|doctor|repair|start|stop|disconnect	Manage and diagnose the generated ChatGPT connection

All CLI options

Flag	Description
-p, --project <dir>	Project root to activate (default: cwd)
-c, --config <file>	Path to a YAML config file
--http	Serve MCP over Streamable HTTP
--port <n>	HTTP MCP port (default 7331)
--host <addr>	Bind address (default 127.0.0.1)
--token <secret>	Primary credential for the HTTP endpoint
--api-key <csv>	Extra API keys (repeatable / comma-separated)
--require-auth	Enforce auth even on a loopback bind
--auth <mode>	HTTP auth mode: none, token, or oauth
--oauth-resource <url>	Canonical public MCP resource URL (normally the public /mcp URL)
--oauth-issuer <url>	External OAuth authorization-server issuer
--oauth-scopes <csv>	Scopes advertised by protected-resource metadata
--oauth-read-scope <scope>	Scope required for MCP read access
--oauth-write-scope <scope>	Additional scope required by mutating tools
--oauth-client-registration <mode>	cimd, dcr, or predefined
--oauth-jwks-uri <url>	Explicit trusted JWKS URI override
--oauth-trusted-jwks-hosts <csv>	Exact trusted JWKS host[:port] values
--oauth-algorithms <csv>	Allowed asymmetric JWT algorithms
--oauth-resource-documentation <url>	Public documentation URL included in protected-resource metadata
--unsafe-oauth-http	Development only: permit loopback HTTP issuer/resource URLs
--dashboard-port <n>	Dashboard port (default 7332)
--no-dashboard	Disable the local dashboard
--tools-preset <id>	vibe | vibe-lite | readonly | full
--tools-groups <csv>	Limit advertised tools to these groups
--tools-enable <csv>	Always-keep tool names
--tools-disable <csv>	Drop these tool names
--policy <mode>	Policy mode at startup: readonly | safe | dev | danger (CLI wins over config)
-v, --version	Print version and exit
-h, --help	Show help

Zero-config first run (new in 1.4.0)

You no longer have to hand-write a config to get the full feature set. On the first run in a project, if no config file exists yet, FolderForge writes a complete folderforge.yaml next to your project and loads it immediately. So this is enough:

npm install -g @musashishao/folderforge
folderforge --project . --http --port 3112 --tools-preset vibe-lite --no-dashboard

The generated folderforge.yaml is batteries-included:

• policy.defaultMode: dev
• tools.preset: vibe-lite (folder-scoped coding set + the full browser group)
• adapters.playwright.enabled: true - so the browser_* tools (navigate, viewport resize, click, type, snapshot, console, network, screenshot, eval) actually run for FE / UI-UX testing instead of returning "Playwright adapter is disabled". Generated adapter args include --isolated so concurrent FolderForge instances do not lock the same browser profile.

Rules:

• It is only written when no config is found in any discovery location (folderforge.yaml, .folderforge.yaml, .folderforge/config.yaml, or $FOLDERFORGE_CONFIG). An existing file is never overwritten.
• Passing --config <file> skips auto-generation entirely.
• A failed write is non-fatal: FolderForge logs a warning and falls back to the built-in defaults.
• CLI flags still override the file (e.g. --port 3112 wins over the file's port).

Playwright is installed as a package dependency, but FolderForge does not download a browser during npm install, global install, or npx startup. Browser installation is an explicit, network-capable setup step:

folderforge setup browser

# Linux hosts that also need Playwright's operating-system packages
folderforge setup browser --with-deps

The setup command resolves the Playwright CLI shipped with the installed FolderForge dependency graph; it does not invoke a mutable npx package. Run folderforge doctor to check whether Chromium is available. Non-browser tools continue to work when Chromium is intentionally absent.

Authentication

FolderForge has three HTTP authentication modes. Stdio remains protected by the local process boundary and does not use the HTTP OAuth flow.

Mode	Intended use	Behavior
none	loopback-only local development	rejected on non-loopback binds
token	scripts and trusted fixed clients	static Bearer or X-API-Key; legacy omitted-mode inference remains supported
oauth	ChatGPT and user-delegated remote access	external OAuth 2.1 authorization server; JWT/JWKS verification and per-tool scopes

When server.http.auth.mode is omitted, existing behavior is preserved: a configured token/API key enables static auth, while a credential-free loopback bind remains local-only. A non-loopback token-mode bind now fails startup unless a credential is explicitly configured; FolderForge never prints generated credentials into logs.

Static token/API-key mode

folderforge --http --auth token --host 127.0.0.1 --port 7331 \
  --token "$(openssl rand -base64 32)"

Clients may send Authorization: Bearer <credential> or X-API-Key: <credential>. Static credentials never act as OAuth credentials, and OAuth mode never falls back to X-API-Key.

OAuth mode for ChatGPT

FolderForge acts as an OAuth resource server only. An established external identity provider owns login, consent, exact redirect-URI validation, Authorization Code + PKCE S256, client identification/registration, refresh and revocation. FolderForge publishes RFC 9728 metadata, validates the access JWT cryptographically, enforces issuer/audience/expiry/not-before/algorithm, and requires folderforge:read before MCP access plus folderforge:write before a mutating tool executes.

For Auth0, the guided path is:

# Personal testing: Auth0 DCR + a temporary Cloudflare quick tunnel.
folderforge connect chatgpt --quick

# Team/production: stable HTTPS URL + predefined OAuth client.
folderforge connect chatgpt --secure \
  --public-url https://mcp.example.com/mcp

The wizard discovers the active Auth0 tenant and issuer, verifies discovery, PKCE S256 and JWKS, creates or reuses the API/scopes idempotently, writes a secret-free receipt, starts the local server/tunnel, and verifies OAuth metadata plus the 401 WWW-Authenticate challenge. It never stores Auth0 Management API tokens, OAuth tokens, authorization codes, client secrets, private keys, PKCE verifiers, API keys, passwords, or cookies.

Lifecycle commands:

folderforge chatgpt status
folderforge chatgpt doctor
folderforge chatgpt repair
folderforge chatgpt start
folderforge chatgpt stop
folderforge chatgpt disconnect

Quick mode is development-only because a restarted temporary tunnel can change the resource URL and JWT audience. Secure mode requires a stable HTTPS URL; the exact ChatGPT redirect URI and final Auth0 client registration remain a minimal external UI step.

Manual/external-IdP configuration remains available:

folderforge --http --auth oauth --host 0.0.0.0 --port 7331 \
  --oauth-resource https://mcp.example.com/mcp \
  --oauth-issuer https://auth.example.com \
  --oauth-scopes folderforge:read,folderforge:write \
  --oauth-client-registration cimd \
  --no-dashboard

Equivalent YAML:

server:
  transport: http
  http:
    host: 0.0.0.0
    port: 7331
    auth:
      mode: oauth
      oauth:
        resource: https://mcp.example.com/mcp
        issuer: https://auth.example.com
        scopes: [folderforge:read, folderforge:write]
        readScope: folderforge:read
        writeScope: folderforge:write
        clientRegistration: cimd

Production OAuth requires HTTPS for both the canonical resource and issuer. Loopback HTTP is available only for deterministic development/tests with --unsafe-oauth-http. The protected-resource metadata URL for the example is https://mcp.example.com/.well-known/oauth-protected-resource/mcp (with a root fallback also served).

Environment equivalents include FOLDERFORGE_HTTP_AUTH, FOLDERFORGE_OAUTH_RESOURCE, FOLDERFORGE_OAUTH_ISSUER, FOLDERFORGE_OAUTH_SCOPES, FOLDERFORGE_OAUTH_READ_SCOPE, FOLDERFORGE_OAUTH_WRITE_SCOPE, FOLDERFORGE_OAUTH_CLIENT_REGISTRATION, FOLDERFORGE_OAUTH_JWKS_URI, FOLDERFORGE_OAUTH_TRUSTED_JWKS_HOSTS, FOLDERFORGE_OAUTH_ALGORITHMS, and FOLDERFORGE_OAUTH_ALLOW_INSECURE_HTTP. Precedence is CLI > environment > YAML

built-in/legacy behavior.

See the one-command Auth0/ChatGPT guide, OAuth setup and ChatGPT validation, the architecture decision, and security hardening.

Develop

npm test          # unit + integration (vitest)
npm run typecheck # tsc --noEmit
npm run build     # emit to dist/

Design goals

• Safe by default
• Local-first
• Auditable
• MCP-native
• Production-minded code structure

Repository structure

• src/ - server, policy, workspace, tools, audit, dashboard
• docs/ - architecture, tools, adapters, security, and roadmap docs
• examples/ - sample client configs
• tests/ - unit and integration tests (incl. the schema-lock guard)

License

Apache-2.0