ForgeCode AI — Production AI-Powered Web IDE

A production-oriented, browser-based cloud AI development environment inspired by Visual Studio Code and Cursor. ForgeCode AI integrates Monaco Editor, official Model Context Protocol (MCP) server, an advanced line-by-line patch & diff review engine, and Voroa Managed PostgreSQL.

imageNode.js imagePostgreSQL imageMCP imageLicense: MIT

Architecture Overview

+-------------------------------------------------------------------------+
| Top Command Bar: Project Selector | File Search | Layout | User Profile  |
+---+----------------------+---------------------------------+------------+
| A | File Explorer        | Central Editor Workspace         | AI Agent   |
| c | (Hierarchical Tree)  | (Monaco Editor / Diff Editor)    | Panel      |
| t |                      | Multi-tab header with dirty dots | (Chat,     |
| i | - src/               |                                 | Context,   |
| v |   - index.ts         |                                 | Proposals, |
| i |   - patchEngine.ts   |                                 | Hunks)     |
| t | - package.json       |                                 |            |
| y | - .env               |                                 |            |
|   |                      +---------------------------------+            |
| B |                      | Bottom Panel: Terminal | Output |            |
| a |                      | Diagnostics | Execution Logs    |            |
| r |                      |                                 |            |
+---+----------------------+---------------------------------+------------+
| Status Bar: Branch | Error/Warn | Line/Col | Encoding | MCP: Connected   |
+-------------------------------------------------------------------------+

Key Capabilities

1. Monaco Editor & Monaco Diff Viewer:

   • Custom dark developer theme (#18181b / #1f1f23).
   • IntelliSense, bracket pair colorization, multi-cursor, and minimap.
   • Side-by-side and inline diff inspection with floating hunk controls ([✓] Accept, [✗] Reject, Apply Selected).

2. Line-by-Line Patch & Diff Engine:

   • Surgical hunk modifications instead of rewriting 1,000-line files for a 3-line change.
   • Myers diff algorithm with sliding-window fuzzy fallback matching.
   • Optimistic concurrency conflict detection (baseSha256).
   • Snapshot rollback history (undo_change) for bit-for-bit reversion.

3. Native Model Context Protocol (MCP) Server:

   • Implements @modelcontextprotocol/sdk Streamable HTTP / Server-Sent Events (SSE) on /mcp.
   • Bearer token authentication with granular scopes (files:read, files:write, patch:propose, patch:apply, git:read, git:write, terminal:execute).
   • 28 standard-compliant tools including project tree discovery, regex code search, file operations, diff proposals, git version control, and direct GitHub push (git_push).
   • 1-click configuration snippet export for Claude Desktop, Cursor, and Antigravity.

4. Multi-Provider AI Architecture:

   • Streaming SSE chat with sliding-window context engine.
   • Adapters for OpenAI (GPT-4o, o3-mini), Anthropic (Claude 3.5 Sonnet), Google Gemini (Gemini 2.5 Flash), and custom OpenAI-compatible endpoints (Ollama, LM Studio).
   • Server-side AES-256-GCM encryption of user API keys.
   • Automatic secret scrubbing of environment variables and private tokens before sending prompts to LLMs.

5. Sandboxed Terminal & Git Integration:

   • Real-time xterm.js web terminal connected over WebSockets (/ws/terminal).
   • Parameterized Git version control (simple-git) for staging, committing, diffing, and branch switching.

6. Voroa.com Deployment & Persistent Storage:

   • Zero-dependency built-in PostgreSQL blob storage driver (FileContent partitioned by project_id).
   • Configurable S3 / Cloudflare R2 object storage driver.
   • Persistent volume local mount driver.
   • Automated Prisma migrations and /healthz health check endpoint.

Model Context Protocol (MCP) Integration

ForgeCode AI exposes a compliant MCP server at:

https://<your-voroa-app-or-host>/mcp

Claude Desktop Configuration (claude_desktop_config.json)

{
  "mcpServers": {
    "forgecode": {
      "url": "https://your-app.voroa.app/mcp",
      "headers": {
        "Authorization": "Bearer mcp_live_YOUR_TOKEN_HERE"
      }
    }
  }
}

Registered MCP Tools Catalog

Smart Git Sync & GitHub Integration

ForgeCode AI features a production-ready, pure-JS Git engine powered by isomorphic-git and authenticated GitHub REST API integrations. It requires zero external Git CLI binaries installed on the server container and operates seamlessly across serverless and isolated container environments like Voroa.com.

1. Smart Git Sync Engine (git_sync)

The git_sync tool safely reconciles changes between your local project workspace and a configured remote repository.

Workflow Steps

1. Validates project ID and resolves workspace working directory.
2. Synchronizes database storage (WorkspaceStorageAdapter) to disk working tree.
3. Inspects index state, working-tree modifications, staged files, and untracked files.
4. Detects whether any Git operation (merge, rebase, cherry-pick, revert) is currently in progress.
5. Acquires per-repository exclusive lock via GitLockManager to prevent race conditions.
6. Fetches latest refs from the configured remote repository.
7. Computes merge base (findMergeBase) and calculates ahead / behind commit distance.
8. Safely fast-forwards or reconciles histories via explicit strategy (safe, ff-only, merge, rebase).
9. Never automatically discards, resets, or stashes user changes without explicit instructions.
10. If merge conflicts occur, preserves conflict markers, aborts destructive steps, and returns structured conflict details.
11. Pushes to remote only when explicitly requested (push: true), requiring force: true for non-fast-forward pushes.
12. Synchronizes disk changes back to database storage (WorkspaceStorageAdapter.syncDiskToStorage).
13. Returns structured status report with commit hashes, ahead/behind counts, and operation summaries.

Parameters

git_sync({
  projectId?: string;      // Project UUID (defaults to active workspace)
  remoteName?: string;     // Remote name (default: "origin")
  branch?: string;         // Target branch (default: current branch or upstream)
  strategy?: 'safe' | 'ff-only' | 'merge' | 'rebase'; // Sync strategy (default: "safe")
  push?: boolean;          // Push local commits to remote after reconciliation (default: false)
  commitMessage?: string;  // Commit message to safely auto-stage & commit changes before syncing
  force?: boolean;         // Explicit opt-in required for force-pushing (warning: may overwrite remote history)
  dryRun?: boolean;        // Preview analysis without mutating working tree or remote (default: false)
  token?: string;          // GitHub Personal Access Token (defaults to GITHUB_TOKEN environment variable)
})

Structured Response Fields

{
  success: boolean;
  projectId: string;
  remote: string;
  branch: string;
  initialHead: string;
  localHead: string;
  remoteHead?: string;
  ahead: number;
  behind: number;
  workingTreeClean: boolean;
  strategy: string;
  fetchCompleted: boolean;
  mergeCompleted: boolean;
  rebaseCompleted: boolean;
  pushAttempted: boolean;
  pushCompleted: boolean;
  conflicts?: string[];
  warnings?: string[];
  message: string;
}

2. Complete Git Status, Diff & History Access

git_status

Returns full structured porcelain repository status:

• currentBranch: Active branch name
• headCommit: Current commit SHA
• upstreamBranch: Tracking branch (e.g. origin/main)
• ahead / behind: Commit distance between local and remote
• staged: Staged file paths
• unstaged: Modified but unstaged file paths
• untracked: New untracked files
• deleted: Deleted file paths
• conflicted: Conflicted file paths (e.g. unmerged files)
• workingTreeClean: Boolean indicating zero uncommitted or untracked changes
• operationInProgress: null | 'merge' | 'rebase' | 'cherry-pick' | 'revert'

git_diff

Generates comprehensive unified diffs with:

• Staged diff (staged: true) or unstaged working tree diff (staged: false)
• Revision range comparison (fromRevision and toRevision)
• File path filter (filePath)
• Line limit pagination (maxLines, default 1000)
• Insertion & deletion file statistics
• Automatic secret scrubbing: All GitHub PATs (ghp_..., github_pat_...), API keys (sk-...), and passwords are redacted ([REDACTED_SECRET]) before diff is returned.

git_history

Retrieves commit log with commit SHA, commit message, author name & email, ISO timestamp, parent commit hashes, and file paths.

3. Full GitHub Repository Synchronization

4. OAuth Scopes & Authorization Model

ForgeCode AI enforces granular OAuth 2.1 scopes for all tools:

Handling Missing Scopes & Reauthorization

If your client token lacks a required scope, the server returns an actionable structured error:

{
  "isError": true,
  "errorCode": "AUTH_SCOPE_MISSING",
  "message": "Permission denied: Missing required MCP scope 'git:read'"
}

To grant missing scopes:

1. Re-run OAuth authorization flow at https://<your-host>/oauth/authorize.
2. Request git:read git:write git:commit along with base scopes (files:read files:write).
3. Or generate an MCP access token in the ForgeCode AI Web UI under Settings → MCP Tokens with full Git permissions.

5. Error Code Reference

The server returns stable, machine-readable error codes in JSON responses:

6. Workflow Examples

A. Checking Detailed Status

// Tool: git_status
{}

B. Previewing Synchronization Safely (dryRun)

// Tool: git_sync
{
  "dryRun": true,
  "strategy": "safe"
}

C. Synchronizing with Remote & Auto-Staging

// Tool: git_sync
{
  "strategy": "merge",
  "commitMessage": "Auto-staged local updates before sync",
  "push": true
}

D. Pushing New Commits

// Tool: git_push
{
  "branch": "main",
  "commitMessage": "feat: add user authentication controller"
}

E. Recovering from Merge Conflicts

If git_sync reports MERGE_CONFLICT:

1. Inspect conflicting files using git_status: check conflicted: [...].
2. Inspect conflict markers (<<<<<<<, =======, >>>>>>>) using read_file or git_diff.
3. Edit files to resolve conflicts using write_file or patch tools.
4. Stage resolved files: git_commit(message: "fix: resolve sync merge conflicts").
5. Run git_sync(push: true) to finish synchronization.

Quick Start & Local Development

Prerequisites

• Node.js 20+ LTS or 22 LTS
• PostgreSQL database (or Voroa / Neon PostgreSQL instance)

1. Clone & Install Dependencies

git clone https://github.com/abhinavstechdev/ForgeCodebynodejs.git
cd ForgeCodebynodejs
npm install

2. Configure Environment

Copy .env.example to .env and fill in your database credentials:

cp .env.example .env

3. Initialize PostgreSQL Database

npx prisma generate
npx prisma db push

4. Run Development Servers

npm run dev

• Frontend (Vite): http://localhost:5173
• Backend API & Healthcheck: http://localhost:3000/healthz
• MCP Endpoint: http://localhost:3000/mcp

Deploying on Voroa.com

1. In Voroa Dashboard, create a Managed PostgreSQL database (PostgreSQL 18).
2. Create a Web Service pointing to this GitHub repository.
3. Set the following environment variables:
   • NODE_ENV: production
   • PORT: 3000
   • HOST: 0.0.0.0
   • DATABASE_URL: [Linked Voroa Database URL]
   • APP_SECRET_KEY: [Generated 64-char hex key]
   • STORAGE_DRIVER: postgres
4. Set Build & Start commands:
   • Build Command: npm ci && npm run build && npx prisma migrate deploy
   • Start Command: npm run start
5. Deploy service and verify via /healthz.

License

MIT © ForgeCode AI