# Free Codin Agent 4 Ever

A client-agnostic Model Context Protocol (MCP) server that gives an AI coding host controlled access to local developer capabilities: files, shell, Git, LSP, browser automation, Windows UI automation, VS Code state, long-running jobs, checkpoints, and resource-aware execution.

This repository is intentionally provider-neutral. It does not require or dispatch work to any hosted model vendor.

## What this public repository contains

- Standard MCP over **stdio** for local MCP clients.
- Standard MCP over **Streamable HTTP** at `/mcp`.
- Legacy MCP HTTP+SSE compatibility at `/sse` + `/messages`.
- Transactional file edits with checkpoints and optimistic SHA-256 preconditions.
- Shell, PTY, background processes, durable jobs, Git, and project inspection.
- Headless language-server operations.
- Isolated Playwright browser automation.
- Optional companion Chrome extension for the user's real browser.
- Optional companion VS Code extension for editor diagnostics/references/debug state.
- Windows UI automation and media helpers.
- Filesystem root allowlisting and resource admission controls.

## Arena / LM Arena

The server itself is plain MCP and is not tied to a specific chat product. Use it with an MCP-capable host or with an Arena deployment/product surface that accepts standard MCP servers. No private Arena API, browser cookie, session token, or reverse-engineered endpoint is included here.

## Fastest installation on Windows

### Option A — download and double-click

1. Download the repository as a ZIP and extract it.
2. Double-click `install.cmd`.
3. Enter the folder that the coding agent is allowed to access.
4. Copy the MCP configuration printed by the installer into your MCP client.

If Node.js 20+ is missing and Windows Package Manager is available, the installer
offers to install Node.js LTS automatically. The agent itself is installed
globally, so the extracted ZIP can be deleted afterwards.

After installation the MCP client does **not** need a repository path. It launches:

```text
free-codin-agent stdio
```

The generated MCP configuration is:

```json
{
  "mcpServers": {
    "free-codin-agent": {
      "command": "free-codin-agent",
      "args": ["stdio"]
    }
  }
}
```

### Option B — npm package

The package is structured for global npm installation:

```powershell
npm install -g free-codin-agent-4-ever
free-codin-agent setup
```

Once the package is published to the npm registry, these two commands are enough.

Useful commands:

```text
free-codin-agent             start MCP over stdio
free-codin-agent setup       choose/configure the allowed workspace
free-codin-agent doctor      verify the local installation
free-codin-agent print-config
free-codin-agent http        start the local HTTP transport
```

Configuration and runtime state are stored in the current user's standard
application-data directories. They are never stored in this public repository.

## Do I need a domain?

**No for local MCP.** A stdio-capable MCP client starts `free-codin-agent`
directly on the same machine, so there is no website, public IP, DNS record,
domain, TLS certificate, or tunnel involved.

**Yes, an HTTPS-reachable endpoint is needed when the MCP host runs somewhere
else and must connect back to the user's computer.** That endpoint can be a
per-user tunnel URL, a domain owned by that user, or a secure relay service.
Every installation should have its own authenticated endpoint; users should not
share one unrestricted public bridge.

A marketing/documentation website is optional and is unrelated to the MCP
transport itself.

## Requirements

- Node.js 20 or newer.
- Windows for the full Windows automation feature set.
- Optional: Chrome for browser automation.
- Optional: FFmpeg for video rendering.
- Optional: Go / TypeScript / Python language servers depending on the projects you inspect.

## Manual developer install

```powershell
npm install
Copy-Item .env.example .env
```

For normal end users, prefer `install.cmd` / `free-codin-agent setup`.
The repository-local `.env` workflow is retained only for development and advanced deployments.

## Start over stdio

This is the preferred local MCP transport:

```powershell
npm start
```

Example generic MCP client configuration for a source checkout:

```json
{
  "mcpServers": {
    "free-codin-agent-4-ever": {
      "command": "node",
      "args": ["<ABSOLUTE_PATH_TO_REPOSITORY>/stdio.js"]
    }
  }
}
```

Replace `<ABSOLUTE_PATH_TO_REPOSITORY>` with the location where **you** cloned
the repository. No machine path, username, drive letter, workspace, or account
is built into the project.

## Start over HTTP

```powershell
npm run start:http
```

Default endpoint:

```text
http://127.0.0.1:3000/mcp
```

When `MCP_API_KEY` is set, clients must send:

```text
Authorization: Bearer <MCP_API_KEY>
```

Without a key, HTTP access is accepted only from a direct loopback connection. Requests arriving through a proxy/tunnel are rejected.

## Security model

This server can edit files and execute commands. Treat it like local developer access.

Recommended public defaults:

1. Keep `MCP_HOST=127.0.0.1` unless you intentionally expose the HTTP server.
2. Set `MCP_ALLOWED_ROOTS` to the repositories the agent may touch.
3. Set a strong `MCP_API_KEY` before any non-loopback exposure.
4. Do not commit `.env`, generated logs, browser profiles, screenshots, clips, checkpoints, memory, or job state.
5. Review destructive tool calls in the MCP client.
6. Use the Chrome pairing token only with the unpacked extension instance you control.

## Configuration

See `.env.example`. Important settings:

| Variable | Purpose |
| --- | --- |
| `FCA_WORKSPACES` | Known repositories, separated by comma or semicolon |
| `FCA_DEFAULT_WORKSPACE` | Default directory for relative paths |
| `FCA_ALLOWED_ROOTS` | Optional filesystem sandbox |
| `MCP_API_KEY` | Bearer token for HTTP transport |
| `MCP_ALLOWED_ORIGINS` | Browser origins allowed to call HTTP endpoints |
| `FCA_CHROME_BRIDGE_ENABLED` | Enable/disable the companion Chrome bridge |
| `CHROME_BRIDGE_TOKEN` | Chrome extension pairing secret |
| `CHROME_EXTENSION_ID` | Optional extension identity pin |
| `VSCODE_BRIDGE_URL` | Local VS Code companion endpoint |

## Chrome companion extension

1. Open Chrome's extension management page.
2. Enable Developer mode.
3. Load `chrome-extension` as an unpacked extension.
4. Set `CHROME_BRIDGE_TOKEN` in `.env`.
5. Open the extension popup and save the same token and port.
6. Optionally set `CHROME_EXTENSION_ID` after Chrome assigns the unpacked extension an ID.

The extension has no hardcoded identity key in this repository.

## VS Code companion extension

The source is under `vscode-extension`. It exposes only a loopback HTTP helper for diagnostics, references, definitions, open files, and debug state.

Its configuration key is:

```text
freeCodinAgent.port
```

Default port: `3005`.

## Verification

```powershell
npm run check
npm run privacy
npm run preflight
npm test
```

## Privacy / publication hygiene

The public source tree intentionally excludes:

- local `.env` files and API keys;
- tunnel URLs and connector URLs;
- browser profiles, screenshots, clips, logs, checkpoints, job/task state, and local memory;
- prior conversation archives;
- fixed Chrome extension identity keys;
- machine-specific repository paths;
- model-provider orchestration code and account-specific integrations.

Run your own secret scanner before publishing any later local changes.

## License

ISC. See `LICENSE`.