Chapter 10

MCP Server & Tools

19 MCP tools, REST API, WebSocket hub, telemetry, and cost tracking — the integration layer.

Architecture

A single Node.js process runs three subsystems — the nervous system that lets all your tools talk to each other:

MCP (stdio)

19 tools exposed via Model Context Protocol. Copilot, Claude, Cursor call these as function calls.

Express (HTTP :3100)

Dashboard UI, REST API, static files. 12+ endpoints for programmatic access.

WebSocket (:3101)

Real-time events. Dashboard subscribes for live slice progress.

Starting the Server

Terminal

# Install dependencies (first time only)
cd pforge-mcp && npm install && cd ..

# Full server: MCP + HTTP + WebSocket
node pforge-mcp/server.mjs

# Dashboard only (no MCP stdio)
node pforge-mcp/server.mjs --dashboard-only

# Custom project path
node pforge-mcp/server.mjs --project /path/to/project

With .vscode/mcp.json configured (created by setup), the server auto-starts when Copilot calls any forge tool.

MCP Tools (19)

Every tool is callable from Copilot Chat, Claude Code, Cursor, or any MCP-compatible client:

Tool	Description
`forge_smith`	Diagnose environment, VS Code config, setup health, version currency
`forge_validate`	Validate setup files — check counts match preset, no placeholders
`forge_sweep`	Scan for TODO/FIXME/HACK/stub/placeholder markers
`forge_status`	Show phases from DEPLOYMENT-ROADMAP.md with status
`forge_diff`	Compare changes against plan's Scope Contract — detect drift
`forge_analyze`	Cross-artifact consistency scoring (0–100, 4 dimensions)
`forge_diagnose`	Multi-model bug investigation — root cause + fix recommendations
`forge_run_plan`	Execute hardened plan: spawn workers, validate gates, track tokens. Supports `--quorum=power` (flagship) and `--quorum=speed` (fast) presets
`forge_abort`	Abort currently running plan execution
`forge_plan_status`	Get latest execution status — per-slice results, tokens, duration
`forge_cost_report`	Cost tracking: total spend, per-model breakdown, monthly trend
`forge_new_phase`	Create new phase plan file + roadmap entry
`forge_ext_search`	Search community extension catalog
`forge_ext_info`	Detailed info about a specific extension
`forge_capabilities`	Machine-readable API surface — tools, intents, config, extensions
`forge_run_skill`	Execute a skill programmatically with step-level tracking
`forge_skill_status`	Get recent skill execution events from hub
`forge_generate_image`	Generate images via Grok Aurora or DALL-E, save with format conversion
`forge_org_rules`	Export org custom instructions — consolidate instruction files for GitHub org-level Copilot config

Discovery: Call forge_capabilities first — it returns the full API surface including tool schemas, config options, and available extensions.

REST API

All endpoints available at http://localhost:3100:

Method	Endpoint	Description
GET	`/api/status`	Current run status
GET	`/api/runs`	Run history (last 50)
GET	`/api/config`	Read `.forge.json`
POST	`/api/config`	Write `.forge.json`
GET	`/api/cost`	Cost report (same as `forge_cost_report`)
POST	`/api/tool/:name`	Invoke any CLI tool via HTTP
GET	`/api/hub`	WebSocket hub status + connected clients
GET	`/api/replay/:run/:slice`	Session replay log for a specific slice
GET	`/api/traces`	All runs from trace index
GET	`/api/traces/:runId`	Single run trace detail
GET	`/api/capabilities`	Full capability surface (JSON)
GET	`/.well-known/plan-forge.json`	Discovery endpoint

WebSocket Hub

Connect to ws://localhost:3101 for real-time events. The dashboard uses this for live progress updates.

Event	When
`connected`	Client connects — includes event history replay
`run-started`	Plan execution begins
`slice-started`	Slice begins execution
`slice-completed`	Slice passes all validation gates
`slice-failed`	Slice or gate fails
`slice-escalated`	Slice escalated to quorum for multi-model consensus
`run-completed`	All slices finish
`run-aborted`	Execution aborted via `forge_abort`
`skill-started`	Skill execution begins
`skill-completed`	Skill finishes all steps
`approval-requested`	Bridge pauses for external approval
`bridge-notification-sent`	Webhook dispatched (Telegram, Slack, Discord)

Telemetry

Every plan execution emits OpenTelemetry (OTLP) traces stored in .forge/runs/<timestamp>/traces.json:

Resource context — project name, version, preset, model
Span hierarchy — run → slice → gate → escalation
Severity levels — INFO for passes, WARN for retries, ERROR for failures
Export — traces are OTLP-compatible — send to Jaeger, Grafana Tempo, or any collector

Cost Tracking

The orchestrator tracks tokens and computes cost per slice using a 23-model pricing table:

Per-slice — tokens in/out, model, duration, USD cost
Per-run — total cost, model breakdown
Monthly — aggregated in .forge/cost-history.json
Model performance — .forge/model-performance.json tracks success rate, avg cost, avg duration per model

The orchestrator auto-selects the cheapest model with >80% historical pass rate. Use --estimate to preview costs before executing.

SDK for Integrators

The pforge-sdk/ package provides a JavaScript/TypeScript API for building integrations:

JavaScript

import { createForgeClient } from 'pforge-sdk';

const forge = createForgeClient({ baseUrl: 'http://localhost:3100' });

// Run smith diagnostics
const health = await forge.smith();

// Get cost report
const cost = await forge.costReport();

// Execute a plan
const run = await forge.runPlan('docs/plans/Phase-1.md', {
  mode: 'estimate'
});

The SDK is currently in scaffold stage (v0.1.0) — API surface defined, implementation in progress.

API Key Configuration

API keys for external providers (xAI Grok, OpenAI) are resolved in order: environment variable → .forge/secrets.json → null.

.forge/secrets.json

{
  "XAI_API_KEY": "xai-...",
  "OPENAI_API_KEY": "sk-..."
}

The .forge/ directory is gitignored by default — secrets never enter version control.

📄 Full reference: capabilities.md, EVENTS.md, tools.json