Forgecraft MCP

ForgeCraft

The quality contract your AI coding assistant works within.

______________________________________________________________________

你聘请了一位人工智能工程师。太棒了。它今天还安装了两次相同的14个VS Code扩展，启动了6个它永远不会清理的Docker容器，你的磁盘在一个会话中从12 GB的空闲空间变为0 KB。 完整磁盘不会正常故障。它同时杀死VS Code、终端、Docker和数据库。

ForgeCraft是您的AI编码助手工作的质量合同，因此构建速度很快 和 不会烧毁房子。

npx forgecraft-mcp setup .

支持： Claude（Claude.md）·Cursor（.Cursor/rules/）·GitHub Copilot（.GitHub/Copilot instructions.md）·Windsurf（.windsurrules）·Cline（.clinerules）·Aider（CONVENTIONS.md）

______________________________________________________________________

人工智能辅助软件开发的质量框架

每一次会议、每一个项目、每一位人工智能助手——都以相同的7个属性进行衡量 生成规范 模型。不是共鸣。不是门楣得分。14分中的分数告诉你差距在哪里以及为什么。

$ 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

______________________________________________________________________

发展环境卫生——公约强制执行

ForgeCraft在每个项目的人工智能指令中注入了可执行的规则，使环境污染成为违反公约的行为，而不是事件。

VS代码扩展 安装前： code --list-extensions | grep -i 。仅当所需主要范围内的版本不存在时才安装。同一个扩展不会在同一天内被下载两次。

Docker容器 创建前检查： docker ps -a --filter name=。如果它存在，请启动它——不要创建它。首选 docker compose up （重复使用）过度裸露 docker run （总是创造新的）。日志大小上限为500 MB。 docker system prune -f 记录为定期维护步骤，而不是紧急情况。

例外情况： 当同一服务的多个容器在插件集或主要版本上存在有意义的差异时，允许使用它们——例如 postgres-pgvector 标准旁边的集装箱 postgres 集装箱。命名容器以反映变体（例如。， db-pgvector, db-timescale)否则，重复数据删除规则适用。

Python虚拟环境 一 .venv 每个项目根。如果Python主版本和次版本匹配，则重用。切勿在子目录中创建venv，除非它是一个独立的可安装包。由标记的未使用依赖项 pip list --not-required.

合成和时间序列数据 在写入超过100 MB的生成数据之前，AI会问：保留原始数据、压缩统计数据还是在运行后删除？超过7天的合成数据集，没有代码引用：要求删除。

通用 如果工作空间在已知构建工件之外增长超过2 GB(node_modules/, .venv/, dist/)，发出警告并停车。永远不要默默地扩大工作空间。

______________________________________________________________________

项目设置一句话

Read the spec in docs/specs/, set up this project with ForgeCraft,
scaffold it with the right tags, recommend the tech stack, start building.

这就是整个入职提示。ForgeCraft读取规范，AI分配标签，ForgeCrafts写入指令文件，发出 Status.md, docs/adrs/, docs/PRD.md, docs/TechSpec.md、钩子和技能。AI具有完整的上下文。你开始建造。

ForgeCraft扫描您的项目，自动检测您的堆栈，并在几秒钟内从116个精心策划的块（SOLID、六边形架构、测试金字塔、CI/CD和24个特定于域的规则集）生成定制的指令文件。

______________________________________________________________________

质量门

质量门是结构化的通过/失败检查——你的AI助手在定义的时刻运行——在提交之前、发布之前、部署之后。它们不是门楣规则。每个关卡都有一个条件、一个证据要求和一个是否必须进行人工审查的标志。

盖茨是按发布阶段组织的，所以你不会在绿地项目的第一天运行发布前的混乱测试：

盖茨标记 requires_human_review: true 不能自动通过——有些检查需要人工。

完整的门库、贡献指南和模式位于 质量门存储库→

______________________________________________________________________

ADR，自动排序

每一个不明显的架构决策都会被记录下来。ForgeCraft汽车序列 docs/adrs/NNNN-slug.md MADR格式——上下文、决策、备选方案、后果。你的AI助手会对过去的选择进行推理。你的团队停止对他们提起诉讼。

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

______________________________________________________________________

AI助手设置vs ForgeCraft

claude init，Cursor的工作区规则或Copilot的说明文件可以帮助您开始。ForgeCraft让你达到生产标准——在每个人工智能助理、每个会话、团队中的每个工程师身上。

工作流程手册

设置后，您的AI具有上下文。这些提示指导工作。复制、粘贴、运行。

→ 完整的工作流程手册 · 在线版本

______________________________________________________________________

运作原理

# First-time setup — auto-detects your stack
npx forgecraft-mcp setup .

flowchart TD
    A["setup .
npx forgecraft-mcp setup ."] --> B["Phase 1 — Analyze
Reads spec · infers tags"]
    B --> C{AI assistant\nin the loop?}
    C -->|"Yes (MCP)"| D["Phase 2 — Calibrate
LLM corrects tags from spec
Writes forgecraft.yaml · CLAUDE.md
PRD.md · hooks · ADR-000"]
    C -->|"No (CLI only)"| E["⚠️ CLI-only mode
Directory heuristics only
→ configure an AI assistant"]
    D --> F["check_cascade
5-step readiness gate
1 · Functional spec
2 · Architecture + C4
3 · Constitution
4 · ADRs
5 · Use cases"]
    F --> G{All 5 passing?}
    G -->|"Stubs / missing"| H["Fill artifacts
docs/PRD.md · docs/adrs/
docs/use-cases.md"]
    H --> F
    G -->|"✅ All pass"| I["generate_session_prompt
Bound context for next task"]
    I --> J["Implement with TDD
RED → GREEN → REFACTOR
+ Documentation Cascade"]
    J --> K["audit_project
Score 0 – 100"]
    K --> L{Score ≥ 90?}
    L -->|"Violations found"| M["WORKFLOWS.md remediation
file_length · layer_violation
hardcoded_url · missing_prd"]
    M --> J
    L -->|"✅ Score ≥ 90"| N["close_cycle
Re-check cascade · assess gates
promote to registry · bump version"]
    N --> O{Roadmap\ncomplete?}
    O -->|"More features"| I
    O -->|"All done"| P["start_hardening
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是一个 设置时CLI工具。运行一次以配置您的项目，然后将其删除——它没有运行时占用空间。

可选择添加MCP哨兵，让您的AI助手诊断并推荐命令：

claude mcp add forgecraft -- npx -y forgecraft-mcp

哨兵是一个单一的工具（约200个令牌）。它读取了三个工件-- forgecraft.yaml, CLAUDE.md, .claude/hooks --导出正确的下一个CLI命令并返回。仅此而已。这是该方法论的核心原则，表现为工具设计：无状态读取器、有限工件集、派生动作。 移除它 在初始设置后回收代币预算。

所得

之后 npx forgecraft-mcp setup，您的项目有：

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

指令文件

这是核心价值。由精心策划的区块组装而成，涵盖：

• SOLID原则 --具体的规则，而不是陈词滥调
• 六边形架构 --端口、适配器、DTO、层边界
• 测试金字塔 --单元/集成/E2E目标，测试加倍分类
• 清洁代码 --CQS、保护子句、不变性、纯函数
• CI/CD和部署 --管道阶段、环境、预览部署
• 域模式 --DDD、CQRS、活动采购（当您的项目需要时）
• 12因子运算 --配置、无状态、可处置性、日志记录

每个区块都来源于成熟的工程文献（Martin、Evans、Wiggins），并适用于人工智能辅助开发。

24标签——AI检测，用户可调

标签告诉ForgeCraft你的项目是什么。在第一次设置时，AI会分析你的规范和代码库并分配它们。您可以在中查看和覆盖 forgecraft.yaml.Blocks合并时没有冲突——随着项目的发展添加或删除标签。

完整的标签列表和贡献指南位于 质量门存储库→

内容深度层次

并非每个项目在第一天都需要DDD。

以...为背景 forgecraft.yaml:

projectName: my-api
tags: [UNIVERSAL, API]
tier: recommended

CLI命令

npx forgecraft-mcp  [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)

MCP哨兵

您可以选择添加ForgeCraft MCP哨兵，让您的AI助手诊断您的项目并建议正确的CLI命令：

哨兵是 单个最小工具 （每个请求约200个令牌，而完整工具套件约1500个令牌）。它检查是否 forgecraft.yaml，您的AI指令文件和钩子存在，然后返回项目当前状态的目标CLI命令。

设计是有意的。 完整的ForgeCraft命令界面（21个操作）位于CLI中，而不是MCP服务器中。MCP服务器只公开一个工具，该工具读取三个工件并返回一个建议。这是工具自身架构中的生成规范原则：无状态读取器、有界工件集、派生动作。该工具练习它写入指令文件的内容。

一个副作用：每个声明的MCP工具在每次调用时都会被模型读取，无论是否被调用。一个工具需要200个代币。21个工具的价格为1500美元。哨兵通过设计保持了该方法的建议MCP预算（≤3个活动服务器）。

推荐工作流程：

1. 将哨兵添加到您的AI助手中（请参阅下面的配置示例）
2. 让你的AI助手运行 npx forgecraft-mcp setup .
3. 从活动MCP配置中删除哨兵
4. 需要刷新或审核时重新添加

Manual MCP config — Claude

添加 .claude/settings.json:

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

Manual MCP config — GitHub Copilot (VS Code)

添加 .vscode/mcp.json 在项目根目录中（如果不存在，则创建它）：

{
  "servers": {
    "forgecraft": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

然后打开Copilot聊天面板，切换到 代理模式，锻造工艺哨兵将出现在工具列表中。

Manual MCP config — Cursor

添加 .cursor/mcp.json:

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

没有MCP客户端？ 没关系，你不需要它。快跑 npx forgecraft-mcp setup . 直接在您的终端。MCP哨兵是可选的；CLI做一切。

已运行 claude init? 使用 npx forgecraft-mcp generate . --merge 与现有的CLAUDE.md合并，在添加生产标准的同时保留自定义部分。

______________________________________________________________________

自由开源

ForgeCraft是免费的。没有限制，没有分层，没有API密钥。

质量门图书馆通过社区贡献而成长。如果你提出一个被接受的门，你的名字就会出现在里面 贡献者.md 你帮助为所有使用人工智能的人提高了门槛。

与团队一起运行？ → 锻造车间.dev

______________________________________________________________________

理论基础

ForgeCraft实现了 生成规范 模型——一个用于评估人工智能生成代码质量的正式7属性框架。白皮书中记录了该模型、S_实现的收敛公式和发布阶段框架。

生成规范：面向无状态读者的实用编程范式 --泽诺多（V3，2026年4月）。开放获取，内政部： 10.5281/zenodo.19637142.背后的学术基础 verify 分数。

白皮书就是理论。ForgeCraft是工具链。为图书馆提出的质量门，可以概括为理论见解，可以纳入未来的白皮书修订版。

行业背景：规范驱动发展融合（ThoughtWorks Tech Radar 2025“采用”；Addy Osmani/Google Cloud AI agent-skills)是实践者运动；生成规范是一种形式化模型，它命名了实践是什么以及为什么它有效。

______________________________________________________________________

配置

微调你的AI助手看到的内容

# forgecraft.yaml
projectName: my-api
tags: [UNIVERSAL, API, FINTECH]
tier: recommended
outputTargets: [claude, cursor, copilot]  # Generate for multiple assistants
compact: true                             # Slim output (~20-40% fewer tokens)

exclude:
  - cqrs-event-patterns    # Don't need this yet

variables:
  coverage_minimum: 90      # Override defaults
  max_file_length: 400

社区模板包

templateDirs:
  - ./my-company-standards
  - node_modules/@my-org/forgecraft-flutter/templates

保持标准新鲜

审核（随时运行，或在CI中运行）

Score: 72/100  Grade: C

✅ Instruction files exist
✅ Hooks installed (3/3)
✅ Test script configured
🔴 hardcoded_url: src/auth/service.ts
🔴 status_md_current: not updated in 12 days
🟡 lock_file: not committed

刷新（项目范围是否更改？）

npx forgecraft-mcp refresh . --apply

或者先在预览模式下（默认）：

npx forgecraft-mcp refresh .   # shows before/after diff without writing

贡献

模板是YAML，不是代码。你可以在不编写TypeScript的情况下添加模式。

templates/your-tag/
├── instructions.yaml   # Instruction file blocks (with tier metadata)
├── structure.yaml      # Folder structure
├── nfr.yaml            # Non-functional requirements
├── hooks.yaml          # Quality gate scripts
├── review.yaml         # Code review checklists
└── mcp-servers.yaml    # Recommended MCP servers for this tag

PR欢迎。看 templates/universal/ 对于格式。

MCP服务器发现

npx forgecraft-mcp configure-mcp 动态发现与您的项目标签匹配的推荐MCP服务器。服务器在 mcp-servers.yaml 每个标签——社区可通过PR贡献。

内置建议包括Context7（文档）、Playwright（测试）、Chrome DevTools（调试）、Stripe（金融科技）、Docker/K8s（infra）等，涵盖所有24个标签。

在安装时从远程注册表获取（可选）：

# In forgecraft.yaml or via tool parameter
include_remote: true
remote_registry_url: https://your-org.com/mcp-registry.json

发展

git clone https://github.com/jghiringhelli/forgecraft-mcp.git
cd forgecraft-mcp
npm install
npm run build
npm test   # 610 tests, 42 suites

许可证

麻省理工学院