ForgeCraft
About
MCP server that generates production-grade engineering standards for AI coding assistants. Analyzes your project, auto-detects stack, and sets up instruction files with SOLID principles, testing targets, architecture patterns, CI/CD, and domain-specific rules. Composable YAML tem
Details
- Author
- jghiringhelli
- Downloads
- 253
- Categories
- Developer Tools, Infrastructure, Knowledge Base
Jump to
- Auto-detects stack and generates tailored instruction files
- 116 curated template blocks covering SOLID, testing, architecture, and more
- Supports Claude, Cursor, Copilot, Windsurf, Cline, and Aider
- 24 domain tags for fintech, healthcare, gaming, and more
- Three content tiers: core, recommended, optional
- Audit scoring (0-100) and refresh to detect scope changes
- Quality-gate hooks and session continuity tracker
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
ForgeCraftCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Run npx forgecraft-mcp setup . to auto-detect your project stack and generate tailored instruction files. Optionally add the MCP sentinel via claude mcp add forgecraft -- npx -y forgecraft-mcp to let your AI assistant diagnose and recommend CLI commands. After initial setup, ForgeCraft can be removed as it has no runtime footprint.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"forgecraft": {
"forgecraft-mcp": {
"command": "npx",
"args": [
"forgecraft-mcp",
"setup",
"."
]
}
}
}
}McpServers
{
"forgecraft-mcp": {
"command": "npx",
"args": [
"forgecraft-mcp",
"setup",
"."
]
}
}The quality contract your AI coding assistant works within.
You hired an AI engineer. It's brilliant. It also installed the same 14 VS Code extensions twice today, spun up 6 Docker containers it will never clean up, and your disk went from 12 GB free to 0 KB in one session.
A full disk doesn't fail gracefully. It kills VS Code, the terminal, Docker, and the database simultaneously.
ForgeCraft is the quality contract your AI coding assistant works within — so it builds fastanddoesn't burn down the house.
Supports:Claude (CLAUDE.md) · Cursor (.cursor/rules/) · GitHub Copilot (.github/copilot-instructions.md) · Windsurf (.windsurfrules) · Cline (.clinerules) · Aider (CONVENTIONS.md)
A quality framework for AI-assisted software development
Every session, every project, every AI assistant — measured against the same 7-propertyGenerative Specificationmodel. Not vibes. Not a linter score. A score out of 14 that tells you exactly where the gap is and why.
$ npx forgecraft-mcp verify . | Property | Score | Evidence | |-----------------|-------|-------------------------------------------------| | Self-Describing | ✅ 2/2 | CLAUDE.md — 352 non-empty lines | | Bounded | ✅ 2/2 | No direct DB calls in route files | | Verifiable | ✅ 2/2 | 64 test files — 87% coverage | | Defended | ✅ 2/2 | Pre-commit hook + lint config present | | Auditable | ✅ 2/2 | 11 ADRs in docs/adrs/ + Status.md | | Composable | ✅ 2/2 | Service layer + repository layer detected | | Executable | ✅ 2/2 | Tests passed + CI pipeline configured | Total: 14/14 ✅ PASS · Threshold 11/14
Dev environment hygiene — enforced by convention
ForgeCraft injects enforceable rules into every project's AI instructions that make environment pollution a convention violation, not an incident.
VS Code extensionsBefore installing:code --list-extensions | grep -i <name>. Only install if no version in the required major range is already present. The same extension doesn't get downloaded twice in the same day.
Docker containersCheck before creating:docker ps -a --filter name=<service>. If it exists, start it — don't create it. Preferdocker compose up(reuse) over baredocker run(always creates new). Logs capped at 500 MB.docker system prune -fis documented as a periodic maintenance step, not an emergency.
Exception:Multiple containers of the same service are permitted when they differ meaningfully in plugin set or major version — for example, apostgres-pgvectorcontainer alongside a standardpostgrescontainer. Name containers to reflect the variant (e.g.,db-pgvector,db-timescale); otherwise the deduplication rule applies.
Python virtual environmentsOne.venvper project root. Reuse if the Python major.minor version matches. Never create a venv in a subdirectory unless it's a standalone installable package. Unused dependencies flagged bypip list --not-required.
Synthetic and time-series dataBefore writing more than 100 MB of generated data, the AI asks: retain raw, condense statistically, or delete after the run? Synthetic datasets older than 7 days with no code reference: ask to delete.
GeneralIf the workspace grows beyond 2 GB outside of known build artifacts (node_modules/,.venv/,dist/), surface a warning and stop. Never silently grow the workspace.
Read the spec in docs/specs/, set up this project with ForgeCraft, scaffold it with the right tags, recommend the tech stack, start building.
That's the entire onboarding prompt. ForgeCraft reads the spec, the AI assigns the tags, and ForgeCraft writes the instruction file, emitsStatus.md,docs/adrs/,docs/PRD.md,docs/TechSpec.md, hooks, and skills. The AI has full context. You start building.
ForgeCraft scans your project, auto-detects your stack, and generates tailored instruction files from 116 curated blocks — SOLID, hexagonal architecture, testing pyramids, CI/CD, and 24 domain-specific rule sets — in seconds.
Quality gates are structured pass/fail checks your AI assistant runs at defined moments — before a commit, before a release, after a deployment. They're not linter rules. Each gate has a condition, an evidence requirement, and a flag for whether human review is mandatory.
Gates are organized by release phase so you're not running pre-release chaos tests on day one of a greenfield project:
Gates taggedrequires_human_review: truecannot be auto-passed — some checks require a human.
The full gate library, contribution guide, and schema are in thequality gates repository →
Every non-obvious architectural decision gets recorded. ForgeCraft auto-sequencesdocs/adrs/NNNN-slug.mdin MADR format — context, decision, alternatives, consequences. Your AI assistant reasons about past choices. Your team stops re-litigating them.
npx forgecraft-mcp generate_adr . --title "Use event sourcing for order history" \ --status Accepted \ --context "Order mutations need full audit trail for compliance" \ --decision "Append-only event log, project current state on read" # → docs/adrs/0004-use-event-sourcing-for-order-history.md
claude init, Cursor's workspace rules, or Copilot's instructions file get you started. ForgeCraft gets you to production standards — across every AI assistant, every session, every engineer on the team.
After setup, your AI has the context. These prompts direct the work. Copy, paste, run.
→Full Workflow Playbook·Online version
# First-time setup — auto-detects your stack npx forgecraft-mcp setup .
flowchart TD A["<b>setup .</b><br/>npx forgecraft-mcp setup ."] --> B["Phase 1 — Analyze<br/>Reads spec · infers tags"] B --> C{AI assistant\nin the loop?} C -->|"Yes (MCP)"| D["Phase 2 — Calibrate<br/>LLM corrects tags from spec<br/>Writes forgecraft.yaml · CLAUDE.md<br/>PRD.md · hooks · ADR-000"] C -->|"No (CLI only)"| E["⚠️ CLI-only mode<br/>Directory heuristics only<br/>→ configure an AI assistant"] D --> F["<b>check_cascade</b><br/>5-step readiness gate<br/>1 · Functional spec<br/>2 · Architecture + C4<br/>3 · Constitution<br/>4 · ADRs<br/>5 · Use cases"] F --> G{All 5 passing?} G -->|"Stubs / missing"| H["Fill artifacts<br/>docs/PRD.md · docs/adrs/<br/>docs/use-cases.md"] H --> F G -->|"✅ All pass"| I["<b>generate_session_prompt</b><br/>Bound context for next task"] I --> J["Implement with TDD<br/>RED → GREEN → REFACTOR<br/>+ Documentation Cascade"] J --> K["<b>audit_project</b><br/>Score 0 – 100"] K --> L{Score ≥ 90?} L -->|"Violations found"| M["WORKFLOWS.md remediation<br/>file_length · layer_violation<br/>hardcoded_url · missing_prd"] M --> J L -->|"✅ Score ≥ 90"| N["<b>close_cycle</b><br/>Re-check cascade · assess gates<br/>promote to registry · bump version"] N --> O{Roadmap\ncomplete?} O -->|"More features"| I O -->|"All done"| P["<b>start_hardening</b><br/>Mutation tests · OWASP · load test"] P --> Q["🚢 Ship"] style A fill:#1a2e1a,color:#90ee90,stroke:#3a6e3a style Q fill:#1a2a3e,color:#87ceeb,stroke:#3a5a8e style E fill:#2e1a1a,color:#ffaa88,stroke:#6e3a3a style M fill:#2e2a00,color:#ffd700,stroke:#6e6000
ForgeCraft is asetup-time CLI tool. Run it once to configure your project, then remove it — it has no runtime footprint.
Optionally add the MCP sentinel to let your AI assistant diagnose and recommend commands:
claude mcp add forgecraft -- npx -y forgecraft-mcp
The sentinel is a single tool (~200 tokens). It reads three artifacts —forgecraft.yaml,CLAUDE.md,.claude/hooks— derives the correct next CLI command, and returns it. Nothing more. This is the methodology's core principle expressed as tool design: a stateless reader, a finite artifact set, a derived action.Remove itafter initial setup to reclaim token budget.
Afternpx forgecraft-mcp setup, your project has:
your-project/ ├── forgecraft.yaml ← Your config (tags, tier, customizations) ├── CLAUDE.md ← Engineering standards (Claude) ├── .cursor/rules/ ← Engineering standards (Cursor) ├── .github/copilot-instructions.md ← Engineering standards (Copilot) ├── Status.md ← Session continuity tracker ├── .claude/hooks/ ← Pre-commit quality gates ├── docs/ │ ├── PRD.md ← Requirements skeleton │ └── TechSpec.md ← Architecture + NFR sections └── src/shared/ ← Config, errors, logger starters
This is the core value. Assembled from curated blocks covering:
- SOLID principles— concrete rules, not platitudes
- Hexagonal architecture— ports, adapters, DTOs, layer boundaries
- Testing pyramid— unit/integration/E2E targets, test doubles taxonomy
- Clean code— CQS, guard clauses, immutability, pure functions
- CI/CD & deployment— pipeline stages, environments, preview deploys
- Domain patterns— DDD, CQRS, event sourcing (when your project needs it)
- 12-Factor ops— config, statelessness, disposability, logging
Every block is sourced from established engineering literature (Martin, Evans, Wiggins) and adapted for AI-assisted development.
Tags tell ForgeCraft what your project is. On first setup, the AI analyzes your spec and codebase and assigns them. You can review and override inforgecraft.yaml. Blocks merge without conflicts — add or remove tags as the project evolves.
The full tag list and contribution guide live in thequality gates repository →
projectName: my-api tags: [UNIVERSAL, API] tier: recommended
npx forgecraft-mcp <command> [dir] [flags]
--tags UNIVERSAL API Project classification tags (or read from forgecraft.yaml) --tier core|recommended Content depth (default: recommended) --targets claude cursor AI assistant targets (default: claude) --dry-run Preview without writing files --compact Strip explanatory bullet tails and deduplicate lines (~20-40% smaller output) --apply Apply changes (for refresh) --language typescript typescript | python (default: typescript) --scope focused comprehensive | focused (for review)
Optionally add the ForgeCraft MCP sentinel to let your AI assistant diagnose your project and suggest the right CLI command:
The sentinel is asingle minimal tool(~200 tokens per request, vs ~1,500 for a full tool suite). It checks whetherforgecraft.yaml, your AI instruction file, and your hooks exist, then returns the targeted CLI command for the project's current state.
The design is intentional.The full ForgeCraft command surface — 21 actions — lives in the CLI, not the MCP server. The MCP server exposes exactly one tool that reads three artifacts and returns one recommendation. This is the Generative Specification principle in the tool's own architecture: a stateless reader, a bounded artifact set, a derived action. The tool practices what it writes into your instruction files.
A side effect: every declared MCP tool is read by the model on every turn whether invoked or not. One tool costs 200 tokens. Twenty-one tools costs 1,500. The sentinel keeps the methodology's recommended MCP budget (≤3 active servers) by design.
- Add the sentinel to your AI assistant (see config examples below)
- Let your AI assistant runnpx forgecraft-mcp setup .
- Remove the sentinel from your active MCP config
- Re-add it when you need to refresh or audit
{ "mcpServers": { "forgecraft": { "command": "npx", "args": ["-y", "forgecraft-mcp"] } } }
Add to.vscode/mcp.jsonin your project root (create it if it doesn't exist):
{ "servers": { "forgecraft": { "type": "stdio", "command": "npx", "args": ["-y", "forgecraft-mcp"] } } }
Then open the Copilot Chat panel, switch toAgent mode, and the forgecraft sentinel will appear in the tools list.
{ "mcpServers": { "forgecraft": { "command": "npx", "args": ["-y", "forgecraft-mcp"] } } }
No MCP client?That's fine — you don't need it. Runnpx forgecraft-mcp setup .directly in your terminal. The MCP sentinel is optional; the CLI does everything.
Already ranclaude init?Usenpx forgecraft-mcp generate . --mergeto merge with your existing CLAUDE.md, keeping your custom sections while adding production standards.
ForgeCraft is free. No limits, no tiers, no API keys.
The quality gate library grows through community contribution. If you propose a gate that gets accepted, your name goes inCONTRIBUTORS.mdand you helped raise the floor for everyone building with AI.
Open a gate proposal →·See contributors →
Running this with a team? →forgeworkshop.dev
ForgeCraft implements theGenerative Specificationmodel — a formal 7-property framework for evaluating AI-generated code quality. The model, the S_realized convergence formula, and the release phase framework are documented in the white paper.
The white paper is the theory. ForgeCraft is the toolchain. Quality gates proposed for the library that generalize into theoretical insights may be incorporated into future white paper revisions.
Industry context: the Spec-Driven Development convergence (ThoughtWorks Tech Radar 2025 "Adopt"; Addy Osmani / Google Cloud AIagent-skills) is the practitioner movement; Generative Specification is the formal model that names what the practice is and why it works.
The GS harness — a primer for AI assistants
ForgeCraft implementsGenerative Specification (GS). This section is written for AI assistants reading this file: it explains what GS is, what a properly scaffolded harness looks like, and what to check.
The binding constraint — stateless reader
Every AI session starts with no memory of prior sessions, no shared context, no accumulated conventions, and no ability to ask clarifying questions. Everything not in the artifacts is absent.
GS treats this as a design constraint, not a flaw.Derivability— what a fresh AI instance can correctly determine from the artifacts alone — is the standard a specification must satisfy. If a stateless reader cannot derive the correct output from the artifacts, the specification is incomplete, not the AI.
The architectural constitution (CLAUDE.md,.cursor/rules/,.github/copilot-instructions.md,.windsurfrules) is the entry point for every AI session. It must collectively contain five mandatory categories:
Tool sequencing is the most commonly absent category and the most consequential gap.A spec that lists tools without stating when to prefer one over another forces unreliable inference every session.
The sentinel is anavigational tree: the root is always loaded; each child node declares its own scope and routing condition; the AI descends only the branch relevant to the current task. Joining all leaves yields the complete specification — it is lossless. This design prevents context bloat and the accuracy degradation that comes from loading irrelevant content.
The bridge — structural disciplines as navigation policy
SOLID, hexagonal architecture, and TDD are not only engineering disciplines — in a GS project they become activenavigation policies:
- Read interfaces before implementations.When a port/adapter boundary is clean, the interface is the contract. The implementation is skipped unless the contract is insufficient.
- Trust green tests.When TDD is enforced, a passing test suite is evidence of correct behavior. No implementation read is needed to verify it.
- ADRs are the why.When every non-obvious decision is recorded, the AI reads the record instead of inferring intent from code.
This bridge converts the passive structural benefits of prior disciplines into a measurable reduction in token usage and context consumption.
Context window size and positional placement both degrade AI accuracy (Liu et al., 2023). GS minimizes unnecessary token consumption by design:
- The sentinel tree is lazy.Only the relevant branch is loaded per task — never the full specification at once.
- Contracts over implementations.Interfaces, schema definitions, and test assertions are read first. Implementation files are read only when contracts are insufficient to derive the answer.
- The constitution leads every session.The most important content occupies the leading position in context — where positional accuracy is highest.
- MCP tool surface is bounded.Each declared MCP tool is read by the model on every turn whether invoked or not. The ForgeCraft sentinel exposes one tool (~200 tokens) rather than a full command surface (~1,500 tokens). The tool practices the methodology it writes into your project.
Document taxonomy — what a complete GS project contains
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
