ForgeSpec MCP Protocol 2.0

📖 Overview

ForgeSpec MCP provides a rigorous, fail-closed coordination substrate for autonomous AI agents and pair-programming assistants. Built specifically for Spec-Driven Development (SDD), it replaces chaotic multi-agent file modifications with cryptographic revisions, scoped file locks, deterministic role profiles, and an immutable audit trail.

ForgeSpec exposes a single canonical protocol: Protocol 2.0 ([email protected]).

⚡ Quick Start

Installation & Execution

# Install dependencies and build
npm ci
npm run build

# Launch the stdio MCP server with a secure cursor secret
FORGESPEC_CURSOR_SECRET="at-least-32-bytes-of-secret-material" npx forgespec-mcp

The server communicates via standard MCP JSON-RPC over stdio. Protocol messages are received on stdin and returned on stdout; all startup diagnostics and preflight warnings are routed to stderr. The entrypoint executable is build/index.js.

Environment Configuration

| Variable | Description | Default | |---|---|---| | FORGESPEC_CURSOR_SECRET | 32+ byte HMAC secret (or comma-separated key ring for zero-downtime rotation) | Ephemeral random secret | | FORGESPEC_DB | Path to the SQLite database file | ~/.forgespec/forgespec.db | | FORGESPEC_DIR | Base directory for ForgeSpec data storage | ~/.forgespec/ | | FORGESPEC_NODE_PATH | Explicit Node binary path for the identity broker | process.execPath |

🔄 SDD 2.0 Lifecycle Pipeline

ForgeSpec enforces a strictly sequenced 8-phase contract progression:

init ➔ explore ➔ proposal ➔ spec ➔ design ➔ tasks ➔ apply ➔ verify

• Cryptographic Revisions: Each contract commit produces a deterministic SHA-256 digest linked to the parent contract and board revision.
• Attempt Gating: Execution transitions from tasks to apply and verify require verified attempt claims and file lease grants.

🛠️ Canonical Tool Catalog (18 Tools)

The server publishes exactly 18 tools in deterministic order, partitioned into 6 domain modules:

| Domain | Tools | Description | |---|---|---| | Boards & Contracts | board_createcontract_commitcontract_querycontract_validate | Project workspaces, phase progression, schema validation, and immutable SDD specs. | | Tasks & Planning | task_definetask_querytask_transition | DAG dependency definition, state machine transitions (ready, in_progress, in_review, done). | | Execution & Attempts | attempt_claimattempt_recoverattempt_renew | Worker assignment, bounded TTL execution attempts, recovery protocol. | | File Leases | lease_reservelease_renewlease_release | Scoped optimistic file reservations preventing write collisions across agents. | | Governance & Events | authority_manageapproval_recordevent_query | Delegated capability grants, human/reviewer sign-offs, HMAC-paginated audit trail. | | Core & Diagnostics | forge_healthforge_negotiate | Capability handshake, profile negotiation, storage and runtime qualification. |

Deterministic Profiles

Four deterministic role profiles expose tailored tool subsets:

• planner: Focuses on contract authoring, task decomposition, and board querying.
• worker: Focused on attempt claiming, file lease reservation, and execution transitions.
• reviewer: Evaluates gate decisions and records verified approvals.
• orchestrator: Full coordination capability across boards, authority delegation, and task pipelines.

🛡️ Security & Identity Threat Boundary

OpenCode Plugin ──private stdio──> Identity Broker ──> Sidecar Store (5 tables)
       │                                     └──── root handle + worker handles
       └─ Signed Identity Envelopes (_identity); no actor fields in tool arguments

1. Identity Isolation: The identity sidecar (5 tables) is physically separated from the domain store (16 fs_* tables).
2. No Actor Fields in Model Payload: Models do not provide caller/actor IDs. The plugin injects cryptographic _identity envelopes validated by the server.
3. Shell-Free Execution: The broker process launches with shell: false to eliminate shell-injection attack surfaces.
4. Token Security: Authority and lease tokens are issued once, returned in memory, and stored exclusively as SHA-256 hashes.
5. HMAC Event Cursors: Pagination cursors for event_query are signed with FORGESPEC_CURSOR_SECRET (supports key ring rotation).
6. Fail-Closed Guarantees: A malformed store, missing metadata, or schema corruption halts startup cleanly. Database reset is supported for fresh stores only.

🧩 OpenCode Integration (opencode-forgespec)

The official OpenCode integration is exported via forgespec-mcp/plugin and packaged as opencode-forgespec.

Why Use opencode-forgespec Instead of Raw MCP?

In ForgeSpec Protocol 2.0, the MCP server operates under a fail-closed cryptographic identity model:

• AI models are prevented from self-assigning caller identities or forging permissions.
• Direct invocation (npx -y forgespec-mcp in mcp) without the identity broker environment throws TRUST_BOOTSTRAP_INVALID by design.
• The opencode-forgespec plugin automatically spins up the private Identity Broker sidecar, initializes trusted key pairs, securely injects bootstrap credentials into forgespec-mcp, and signs every tool call with session-bound _identity cryptographic envelopes.

Installation

Install the plugin in your project (or in your OpenCode configuration directory):

# In your local project repository
npm install --save-dev opencode-forgespec

# Or globally for your user profile
npm install -g opencode-forgespec
# (On Windows, you can also install directly in %USERPROFILE%\.config\opencode)

Configuration in opencode.json / opencode.jsonc

Add "opencode-forgespec" to the "plugin" array in your project or global opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-forgespec"
  ]
}

[!WARNING] Do not define a manual "forgespec" entry under "mcp". The plugin registers and connects the authenticated MCP server automatically.

[!IMPORTANT] After installing or configuring opencode-forgespec, restart OpenCode to initialize the private identity broker. Ensure Node 22+ is available on your system path.

Available Tools in OpenCode

All 18 canonical ForgeSpec tools are automatically exposed to OpenCode agents with the forgespec_ prefix:

• forgespec_board_create, forgespec_contract_commit, forgespec_contract_query, forgespec_contract_validate
• forgespec_task_define, forgespec_task_query, forgespec_task_transition
• forgespec_attempt_claim, forgespec_attempt_recover, forgespec_attempt_renew
• forgespec_lease_reserve, forgespec_lease_renew, forgespec_lease_release
• forgespec_authority_manage, forgespec_approval_record, forgespec_event_query
• forgespec_forge_health, forgespec_forge_negotiate

🗄️ Storage Architecture (16 STRICT Tables)

ForgeSpec utilizes an atomic, qualified SQLite schema with 16 strict fs_* tables:

fs_schema_meta · fs_boards · fs_tasks · fs_task_dependencies · fs_gates · fs_gate_decisions
fs_attempts · fs_contracts · fs_leases · fs_lease_scopes · fs_authority · fs_authority_revocations
fs_approvals · fs_audit_events · fs_evidence · fs_idempotency

• Prerequisites: Requires SQLite STRICT table support, JSON1, foreign keys (PRAGMA foreign_keys = ON), and WAL journal mode.
• Further architecture details are documented in docs/architecture.md and docs/protocol-2.md.

🧪 Verification & Quality Contract

The complete runtime contract and documentation consistency are verified with:

# Run unit, domain, security, and integration tests (229+ tests)
npm test

# Check strict TypeScript types
npm run lint

# Compile production bundle
npm run build

# Run runtime smoke preflight
npm run runtime:smoke

📄 License & Threat Model Notice

Distributed under the MIT License.

[!NOTE] The private stdio broker boundary prevents language models from tampering with session identity. However, it is not an OS-level user security boundary. Host isolation should be applied when untrusted local users share execution environments.