# context-forge [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/ecorkran/context-forge  
**GitHub Stars:** 5  
**npm Downloads (last month):** 3431  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/context-forge

## Description
Automate and accelerate complex projects.  Fast, effective, and consistently structured.  MCP server, Claude Skills, CLI.  JSON output available for AI agents.

## Tools
Capabilities this server exposes over MCP:

- **agent_onboard** — Step-by-step instructions for setting up a new Context Forge project and guiding the user into their first phase of work. Returns an onboarding recipe the agent should follow. Optionally accepts a project name.
- **agent_quickstart** — Structured capability schema for machine consumers. Returns tool groupings, quickstart sequence, and CLI equivalents — designed for orchestrators and CI pipelines, not human-supervised sessions.
- **project_list** — List all configured Context Forge projects. Returns project IDs, names, current slices, and other summary fields. Use this to discover available projects before calling project_get or project_update.
- **project_create** — Create a new Context Forge project entry with sensible defaults. Returns the same shape as project_get (full ProjectData plus introspection when projectPath is provided). Does NOT install guides, commands, or configure the IDE — those are separate operations.
- **project_get** — Get full details for a specific Context Forge project by ID. Returns all project fields including configuration, custom data, and timestamps. When the project has a projectPath, the response includes an `introspection` field with: slicePlan (totalSlices, completedSlices, summary), currentTasks (totalTasks, completedTasks, inferredStatus, summary), and artifacts (presence flags for slicePlan, HLD, arch, spec, currentSliceDesign, currentTaskFile). Use project_list first to find project IDs.
- **project_update** — Update configuration fields on an existing Context Forge project. Provide the project ID and any fields to change (e.g., fileSlice, instruction, developmentPhase). Returns the full updated project. Does not delete or replace — only modifies specified fields.
- **project_schema** — Returns the full project data schema including field definitions, aliases, groups, and enum values. Use this to discover available fields for project_update, understand field types, and find short aliases for field names.
- **project_detect** — Report what is in a directory and which adoption outcome applies (opted-out, adoption-incomplete, already-planned, brownfield, greenfield). Judges the given directory as is and works on unregistered projects. Read-only. Failures return a JSON error envelope with a stable code.
- **workflow_future** — Aggregate future work items across all slice plans in a project. Returns a FutureWorkCollectorResult with groups (by initiative), totals, and a markdown summary. Two source patterns are supported: (1) inline ## Future Work sections in regular slice plans, (2) standalone *-slices.future.* files whose entire main body is future work. Response shape: { projectPath, groups[], totalItems, pendingItems, completedItems, markdown }. Each group: { initiativeIndex, initiativeName, sourceFile, items[], totalItems, pendingItems, completedItems }. Each item: { index, name, done, sourceFile, sourceInitiativeIndex, sourceInitiativeName }.
- **workflow_status** — Get the current workflow status for a project. Returns project phase, active slice status (needs-design, needs-tasks, in-implementation, complete), task progress, and slice plan overview. Response shape: { project, phase, activeSlice: { name, index, status, taskProgress?, retroactive? }, slicePlan?, summary }.
- **workflow_next** — Get the recommended next action for a project based on its current state. Returns a prioritized recommendation with rationale and optional suggested CLI command. Response shape: { recommendation, rationale, suggestedCommand?, slice?, phase?, summary, offers?: [{ id, message }] }. offers are optional suggestions (e.g. id "setup-ci"); key on id, never on message.
- **workflow_check** — Run consistency checks on a project to detect mismatches between related artifacts. Detects: task completion vs. slice plan checkbox, frontmatter status vs. computed state, missing artifact cross-references, plan checkbox vs. frontmatter status, duplicate slice indices, missing plan status field, plan status vs. entries, architecture status vs. plans, pending PM decisions in a slice design (warning only, never blocks). Defaults to all-slices mode; provide sliceIndex to narrow to one slice. With fix=true, applies non-destructive corrections to fixable findings. With worktrees, each fix is written only in the checkout that owns it; writes into other checkouts are committed there, and fixes left unwritten are listed in deferred with a reason. Response shape: { projectPath, findings[], totalFindings, errors, warnings, infos, summary, fixed?, fixLog?, fixErrors?, deferred?, commits? }.
- **storage_backup** — Create a versioned timestamped backup of the projects.json data file. Keeps the last 10 backups, automatically pruning older ones. Response shape: { storagePath, backedUp: string[] }.
- **context_build** — Build a complete context prompt for a Context Forge project. This is the primary tool for generating structured context blocks. Optionally override project parameters (fileSlice, instruction, etc.) without modifying the stored project. Returns the assembled context ready for use.
- **template_preview** — Preview a context prompt with specified parameters without modifying the stored project or triggering any side effects. Use this to explore what context would be generated with different configurations before committing to a context_build.
- **prompt_list** — List available prompt templates from the project-local ai-project-guide. Requires guides to be installed (cf guides install). Returns template names and metadata. Use prompt_get to retrieve the full content of a specific template.
- **prompt_get** — Get the full content of a specific prompt template from the project-local ai-project-guide. Requires guides to be installed (cf guides install). Returns the raw template text.
- **guide_status** — Check the installation status of the AI project guide for a project. Returns whether the guide is installed, what method was used (submodule/clone/tarball), current version, latest available version, and whether an update is available.
- **guide_install** — Install the AI project guide into a project directory. Strategies: tarball (default; plain files with no git wiring, simplest for teams), submodule (version-pinned and updatable, but teammates must run git submodule update), clone (a full working copy you can commit to, larger checkout). Omit strategy to use the guide.git_strategy config value. Error if the guide is already installed — use guide_update instead.
- **guide_update** — Update an existing AI project guide installation to the latest version. Uses the same strategy that was used for installation. Error if the guide is not installed — use guide_install first. Updates may require branch confirmation: if the current branch is not the configured trunk/integration branch, this tool returns an error asking you to retry with confirm: true. That response is not a transient failure — it is the expected first step of a two-call confirmation flow (there is no interactive prompt in this context).
- **introspection_slice_plan** — Parse a slice plan document and return structured data: entries with index, name, status, isChecked, plus totalSlices and completedSlices counts.
- **introspection_tasks** — Parse a task file and return structured data: items with name and done status, plus totalTasks, completedTasks, and inferredStatus.
- **introspection_frontmatter** — Extract YAML frontmatter from a markdown file. Returns found (boolean) and data (key-value pairs).
- **introspection_documents** — Detect methodology documents for a given slice index. Returns paths to sliceDesign, taskFile(s), architecture, and slicePlan if they exist.
- **introspection_future_work** — Parse the Future Work section from a slice plan document. Returns items with index, name, and done status.
- **project_structure** — Build the full project model for a Context Forge project. Returns structured data including foundation docs, project architecture, initiatives with slices and tasks, future slices, quality/investigation/maintenance docs, and devlog status. Equivalent to parse.py build_model() output.
- **worktree_list** — List all worktree contexts for a project. Returns worktree IDs, names, index ranges, and workflow state. Use this to discover available worktrees before calling worktree_get or worktree_update.
- **worktree_get** — Get full details for a specific worktree context by ID or name. Returns all worktree fields including index range, workflow state, and paths.
- **worktree_init** — Create a new worktree context for a project. The first worktree triggers forward migration, moving existing workflow fields into the default worktree (`isDefault: true`, range 100-799). Returns the created worktree, whether migration occurred, and any index range overlaps.
- **worktree_update** — Update fields on an existing worktree context. Provide the worktree ID or name and any fields to change. Returns the full updated worktree context.
- **worktree_rm** — Remove a worktree context from a project. If this is the last worktree, triggers reverse migration restoring workflow fields to the project. Returns the removed worktree and whether migration occurred. When other worktrees remain, restoredRange is the default worktree's (`isDefault: true`) new range after the removed range was handed back to it; rangeNotRestored { reason, defaultRange } says why it was not (range-override, not-adjacent, would-overlap). defaultWorktree { id, name } identifies that worktree whenever either is present.
- **config_get** — Get configuration. With a key, returns that key's value, source, and description. Without a key, returns all keys with current values, sources, and defaults. Resolution order: project config → user config → built-in default.
- **config_set** — Set a configuration key to a new value at user or project scope. Use scope="user" for machine-wide defaults, scope="project" to override for a specific project.
- **context_summarize** — Update a project's session state summary. Persists the provided summary text as the project's recent events, which will be included in subsequent context_build output. Use this after significant work milestones, context switches, or to record session progress for continuity. Analogous to Claude Code's /compact but for project-level state.
- **server_version** — Returns the Context Forge MCP server name and version.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "context-forge": {
    "command": "npx",
    "args": ["-y","@context-forge/mcp"]
  }
}
```

## Documentation

## What context-forge does

context-forge provides a structured project context engine for AI-assisted software development. It works with the ai-project-guide methodology, taking a project from concept through initiative planning, architecture, slice planning, slice design, task breakdown, implementation, and integration. Each phase produces linked documents, while slices contain tasks with tracked completion state.

The system maintains a navigable project hierarchy so humans and agents can inspect the current phase, active slice, task state, and remaining work. It supports multiple projects and identifies the relevant project from the working directory. For parallel development, separate git worktrees can hold independent phase, slice, and task contexts.

## How it works

The `cf` command manages project setup and state. `cf init` creates a project, installs the relevant guides, configures an IDE, and can install slash commands. `cf status` gives a short state view, while `cf project get` provides more detail. The `/cf:build` workflow assembles the project material an agent needs into a structured prompt.

The MCP server makes project context available to compatible AI clients. Its `agent_quickstart` capability helps an agent begin using the system, and MCP tools expose project information and workflows alongside the CLI and slash commands. Commands can produce JSON, allowing agent pipelines and other automation to consume results without parsing terminal-oriented output.

Guide installation supports three strategies. `tarball` places ordinary files in the repository, `submodule` keeps a version-pinned Git submodule, and `clone` installs a full working copy. The guide can later be updated with `cf guides update`.

## Setup and configuration

Node.js 20.18 or newer is required. The standalone installation uses the global npm package:

```bash
npm install -g @context-forge/context-forge
```

Add the MCP server through a stdio configuration using `npx @context-forge/mcp`. Claude Code can register it with `claude mcp add --transport stdio context-forge -- npx @context-forge/mcp`. Cursor, Windsurf, and other MCP clients can use the equivalent command-and-arguments configuration. OpenAI Codex CLI uses a `context-forge` entry in `~/.codex/config.toml`.

After installation, run `cf init` in a project. The `--ide` option supports Claude Code, VS Code Copilot, Cursor, and Codex-oriented setups. Manual commands such as `cf guides install`, `cf setup-ide`, and `cf install-commands` provide more control over files and command installation. An alternative is installing Squadron, whose `sq setup` installs and configures Context Forge and related commands.

## Tools and capabilities

- Tracks methodology phase, project artifacts, slices, tasks, and completion state.
- Recommends the next workflow action with supporting rationale.
- Builds structured context for an AI session.
- Manages multiple projects and separate worktree contexts.
- Produces JSON output for commands and automation.
- Installs project guides, IDE rules, skills, and slash commands for supported targets.

## Limitations and notes

The workflow is intended for substantial projects and may be excessive for small utilities. The project guide must be version 0.22.6 or newer for `cf build`; older installations can be repaired with `cf guides update`. The Context Visualizer is a separate tool rather than part of the MCP server. Guide installation requires access to GitHub, and guide updates or commits depend on the project being a suitable Git repository.

_Full upstream README: https://allmcps.com/mcp/context-forge/readme_