stoa MCP

斯托·麦克普

把一句话变成一个完整的规范，让任何人工智能编码工具都能构建出你真正想要的东西。

Stoa是一个规范编译器。你用简单的英语描述你想要什么。Stoa运行一个5级管道，将其转化为一个包含设计标记、约束、验收标准和测试场景的结构化规范。然后你把这个规范输入到Lovable、Bolt、Cursor、Claude Code、v0——任何工具——它们都构建了同样的东西。

在没有规范的情况下，对5个不同的AI工具给出相同的提示，会产生5个完全不同的应用程序。使用Stoa规格，所有5个都符合您的设计。

______________________________________________________________________

安装

npm install -g stoa-mcp

需要Node.js 18或更高版本。

______________________________________________________________________

快速入门（5分钟）

1.创建项目

mkdir my-app && cd my-app
stoa init

这创建了一个 .stoa/ 包含Stoa所需一切的文件夹：

.stoa/
  moodboard/notes.md    ← your design direction (colors, layout, style)
  moodboard/tokens.json  ← auto-generated machine-readable design tokens
  context.md            ← dependencies, conventions, brand voice
  lessons.md            ← project memory (grows automatically)
  guardrails/           ← rules the AI must follow
  roles/                ← AI personas (Builder, Fixer, Planner)
  presets/              ← your saved custom style presets
  specs/                ← saved specifications

每一个新项目都始于 清洁 样式预设（白色、最小、线性样式）。您生成的每个规范都将自动包含这些设计标记。

2.设置你的moodboard（可选但功能强大）

您的项目已经有一个可用的设计系统。检查一下：

stoa moodboard

想要不同的风格吗？ 选择预设：

stoa moodboard preset

使用箭头键浏览4个带有实时预览的内置预设：

• 清洁 --白色，简约，线性/Vercel风格
• 黑暗 --深色背景，柔和的口音，GitHub/Raycast风格
• 温暖 --奶油色调，友好的SaaS感觉
• 加粗 --高对比度、尖角、野兽派

或直接申请： stoa moodboard preset dark

想要定制吗？ 在终端中交互式编辑：

stoa moodboard edit

引导您逐一浏览每个字段（颜色、排版、布局）。按Enter键保留，键入新值进行更改，或 q 随时退出。

有你喜欢的设计截图吗？ 运行：

stoa moodboard describe

这将打开Finder中的moodboard文件夹——将屏幕截图放入，按Enter键。如果您有Anthropic API密钥，Stoa将分析图像并为您编写设计系统。如果没有，它会打印一个提示，你可以粘贴到任何克劳德聊天中。

保存您的自定义样式 用于跨项目重用：

stoa moodboard save-preset my-brand

3.完善你的想法

stoa refine "Personal finance tracker to log expenses and view spending by category"

Stoa跑了5个阶段：

1. 问题陈述 --使用moodboard中的数据模型、文件结构和设计标记将句子扩展为完整的规范
2. 验收标准 --准确定义“完成”的含义
3. 约束条件 --人工智能必须做什么，不能做什么，以及要避免的常见错误
4. 分解 --将大任务分解为子任务（或说“不需要分解”）
5. 场景 --生成您可以在构建后验证的测试用例

精炼后，Stoa：

• 将规范保存为可读的markdown文件 .stoa/specs/
• 自动将第一阶段复制到剪贴板
• 显示交互式菜单：

Spec saved to .stoa/specs/personal-finance-tracker/
Spec Score: 5 / 5

→ Stage 1 description copied to clipboard
  Paste into Lovable, Bolt, v0, or any AI tool

What next?
  [b] Build with Claude Code
  [c] Copy spec to clipboard
  [e] Export as single markdown
  [v] View spec files
  [q] Done

• \[b\] 构建 --启动预装规范的Claude Code
• \[c\] 复制 --将完整规范重新复制到剪贴板（如果复制了其他内容，则很有用）
• \[e\] 出口 --将所有5个阶段作为一个标记写入 specs//spec.md 在项目根目录中（可见，不隐藏在内部 .stoa/)
• \[v\] 查看 --在Finder中打开spec目录
• \[q\] 完成 --出口

4.建造

选项A——优化后按\[b\]：

最快的路径。按 b 在后精炼菜单中，Claude Code立即开始构建。

选项B——粘贴到任何AI工具中：

打开Lovable、Bolt、v0或任何AI编码工具。按Cmd+V。规范已在剪贴板上。AI完全按照您的指定构建。

选项C——手动使用克劳德代码：

claude "Read the spec in .stoa/specs/personal-finance-tracker/ and build it. Follow all constraints and subtasks."

选项D——使用带Claude Code扩展名的游标：

在Cursor中打开项目文件夹。从侧边栏打开Claude Code。粘贴构建提示。

5.验证

构建完成后，运行测试场景：

stoa scenarios run

Stoa将逐一介绍每个场景：

Scenario 1/5: Happy path — add expense and verify summary

  GIVEN:
  Add 3 expenses in different categories. Navigate to Dashboard.

  EXPECTED:
  Each category shows in the donut chart. Total matches the sum.

  Pass? [y/n/s(skip)] →

在浏览器中打开你的应用程序，按照GIVEN的指示操作，检查EXPECTED是否匹配。按 y 对于通行证， n 对于失败， s 跳过。

最后你会得到一个总结：

Results: 4 passed, 1 failed, 0 skipped
Failed:
  - "Category filter shows correct subset"

如果失败了，请向Claude Code描述问题，它会解决的。

______________________________________________________________________

向现有应用程序添加功能

Stoa知道代码何时已经存在。在第一次构建之后，再次运行refine：

stoa refine "Add monthly budget limits per category with progress bars on the dashboard"

第一阶段将参考您现有的文件、组件和设计系统。规范中说“修改Dashboard.tsx”，而不是“从头开始构建财务跟踪器”

______________________________________________________________________

更改设计

切换预设、交互式编辑或两者兼而有之：

stoa moodboard preset dark       # switch to dark theme
stoa moodboard edit              # tweak individual values
stoa refine "Redesign the app to match the updated design system"

Stoa生成了一个迁移规范——什么变化，什么保持不变，确切的新旧令牌映射。

______________________________________________________________________

项目上下文文件

中的所有文件 .stoa/ 是可选的。使用你需要的东西，忽略你不需要的东西。

context.md

打开方式 stoa edit context。添加您的堆栈首选项：

# Project Context

## Brand Voice
Friendly but professional. Use "Save" not "Submit". Error messages explain what went wrong and what to do.

## Dependencies
Use date-fns for dates, not moment. Use HeroUI for all UI components. Use zustand for state management.

## UI Library
HeroUI (https://www.heroui.com) — buttons, inputs, cards, modals, tables

## Code Conventions
PascalCase for components. One component per file. Test files next to source files.

这些会自动注入到每个精炼过程中。你再也不用重复“我们使用HeroUI”了。

出租.md

此文件会自动增长。在构建失败后，告诉Claude Code：

将我们刚刚修复的内容添加到.stoa/lessons.md

示例条目：

## 2026-03-14: HeroUI + Tailwind v4 invisible components
**What happened:** HeroUI components rendered in the DOM but were invisible.
**Prevention:** Add @source "../node_modules/@heroui/theme/dist/**/*.js" to index.css after @import "tailwindcss".

每一次未来的改进都包括过去的经验教训，作为需要避免的失败模式。您的项目随着每次构建而变得更加智能。

______________________________________________________________________

CLI参考

设置

stoa init

创建 .stoa/ 在当前目录中，使用Clean样式预设、5个护栏和3个角色。每个项目运行一次。

stoa edit moodboard          # open moodboard in VS Code/Cursor
stoa edit context             # open context.md
stoa edit lessons             # open lessons.md

在最佳可用编辑器中打开文件。检测顺序：光标→ VS Code→ $EDITOR → macOS默认值→ nano.

______________________________________________________________________

情绪板

stoa moodboard

显示当前moodboard状态：活动样式、颜色计数、图像计数和可用命令。

stoa moodboard preset

互动。 浏览4个内置预设（干净、黑暗、温暖、粗体）+任何带有箭头键的自定义预设。显示带有颜色、排版和参考的实时预览。按 进入 为了应用， q 取消。

您也可以不使用选择器直接申请：

stoa moodboard preset dark

stoa moodboard edit

互动。 逐一浏览每个领域：设计方向→ 颜色（每种单独）→ 排版→ 布局→ 组件样式→ 参考文献按 进入 以保持当前值。键入要替换的新值。类型 q 在任何时候退出。

stoa moodboard describe

互动。 打开 .stoa/moodboard/ Finder中的文件夹，以便您可以拖动屏幕截图。按 进入 当准备好。如果你有API键，Stoa会用AI分析图像，并自动编写设计系统。在没有API密钥的情况下，它会打印一个提示，您可以将其粘贴到任何Claude聊天中，并将其与屏幕截图放在一起。

stoa moodboard sync

使再生 tokens.json 从 notes.md。通常在预设或编辑后自动发生，但如果您进行了编辑，请运行此程序 notes.md 用手。

stoa moodboard save-preset my-brand

将当前moodboard另存为 .stoa/presets/my-brand.json.可跨项目重用--显示在 stoa moodboard preset 拾取器。

______________________________________________________________________

精炼

stoa refine "Build a waitlist page with email signup and referral system"

运行5级管道。完成后，显示交互式菜单：

选项：

stoa refine "task" --mode api         # Force Anthropic API (needs key)
stoa refine "task" --mode claude-code # Force Claude Code CLI
stoa refine "task" --mode clipboard   # Get prompts without AI calls (free)
stoa refine "task" --role planner     # Use a specific role
stoa refine "task" --stages clarify,structure  # Run specific stages only

______________________________________________________________________

规格

stoa specs list                # List all saved specs with dates and stage count
stoa specs show          # Print a spec's contents to terminal

规格保存在 .stoa/specs// 每个阶段有一个markdown文件。这 [e] 导出写入组合 spec.md 到可见 specs/ 项目根目录中的文件夹。

______________________________________________________________________

场景

stoa scenarios list              # List scenarios for the latest spec
stoa scenarios list        # List scenarios for a specific spec
stoa scenarios run               # Walk through scenarios interactively
stoa scenarios run         # Run scenarios for a specific spec

互动。 每个场景都显示了GIVEN（设置什么）和EXPECTED（检查什么）。按 y 对于通行证， n 对于失败， s 跳过。在末尾显示摘要。

______________________________________________________________________

审查

stoa review                    # Review the latest spec
stoa review              # Review a specific spec

互动。 打开每个阶段进行审查。接受、编辑或跳过。编辑后，可以选择重新运行受影响的管道阶段。

______________________________________________________________________

构建和验证

stoa build                     # Build the latest spec with Claude Code
stoa build               # Build a specific spec
stoa verify                    # Run blind test verification
stoa verify              # Verify a specific spec

构建为您提供了一个选择：一次构建全部或逐个子任务构建。验证在构建后以交互方式运行场景。

______________________________________________________________________

护栏和角色

stoa guardrails list           # List active guardrails
stoa guardrails show     # View a guardrail's content
stoa guardrails add      # Add a new guardrail
stoa guardrails remove   # Remove a guardrail
stoa roles list                # List available roles
stoa roles show          # View a role's content
stoa roles add           # Add a new role
stoa roles remove        # Remove a role

护栏是注入到每个优化中的规则（例如“不要删除现有代码”）。角色是通过以下方式使用的AI角色 --role 旗帜。

______________________________________________________________________

配置

stoa config                      # View current settings
stoa config set apiKey      # Set Anthropic API key
stoa config set model     # Set model (default: claude-sonnet-4-6)
stoa config set mode       # Set default mode: api, claude-code, clipboard

______________________________________________________________________

执行模式

Stoa自动检测：API密钥→ api，PATH中的Claude代码→ claude-code，否则→ clipboard.

在剪贴板模式下，Stoa打印每个阶段的提示。粘贴到任何AI聊天（Claude、ChatGPT、Cursor）并将响应复制回来。同样的管道，只是手动的。

______________________________________________________________________

键盘快捷键

所有交互式命令都支持以下命令：

______________________________________________________________________

与光标（MCP）一起使用

在Cursor中添加Stoa作为MCP服务器。创建或编辑 .cursor/mcp.json 在您的项目中：

{
  "mcpServers": {
    "stoa": {
      "command": "node",
      "args": ["/path/to/global/node_modules/stoa-mcp/dist/index.js"]
    }
  }
}

查找全局路径：

echo "$(npm root -g)/stoa-mcp/dist/index.js"

然后在Cursor的Agent聊天中：

Use the refine_task tool with title: "My App" and description: "description of what I want"

与Claude Code一起使用

Stoa直接与Claude Code合作。精炼后：

1. 按 [b] 在后精炼菜单中--自动启动Claude Code
2. 或者复制规范并粘贴： claude "Read the spec in .stoa/specs// and build it"
3. 或使用 stoa build 获得完整的指导体验

______________________________________________________________________

运作原理

五级管道

第一阶段：问题陈述 --将你的一句话想法扩展为一个完整的规范。包括数据模型、文件结构、CLI/API接口、设计令牌（来自moodboard）和明确的假设。

第二阶段：验收标准 --生成3个可验证的“完成时”条件。每个都足够具体，您可以在浏览器或终端中进行测试。

第三阶段：约束 --产生四类：

• 必须做的事 --不可协商的要求
• 必须注意 --要避免的事情（错误的库、反模式）
• 偏好 --很高兴有你的背景.md
• 故障模式 --需要注意的常见错误（包括classes.md）

第四阶段：分解 --将复杂任务分解为有序的子任务，或者对小任务说“不需要分解”。

第五阶段：情景 --生成给定/预期的测试用例。这些都是盲目的测试——构建你的应用程序的人工智能永远不会看到它们。您在构建后进行验证。

项目意识

当你奔跑时 stoa refine 在已经有代码的项目中，Stoa扫描：

• package.json --知道你的堆栈（React、Vue、Tailwind等）
• src/ 目录——了解您现有的组件
• .stoa/specs/ --知道以前建造过什么
• Moodboard——了解你的设计系统
• context.md --了解您的依赖关系和约定
• lessons.md --知道要避免过去的错误

规范按名称引用现有文件，并说“添加到”而不是“重建”

______________________________________________________________________

初学者模板

stoa init 船舶配备：

5护栏：

• explain-changes --AI解释了它改变了什么以及为什么
• dont-delete-code --未经明确请求，请勿删除现有代码
• ask-when-unclear --停下来问，而不是猜测
• run-tests --更改后运行测试
• small-changes --做出专注的小改变

3个角色：

• Builder --编写新功能
• Fixer --修复故障上下文中的错误
• Planner --分解大型任务

4种风格预设：

• Clean --白色，最小，线性/Vercel（默认应用）
• Dark --深色背景，紫色调，GitHub/Raycast
• Warm --奶油色，琥珀色，Cal.com/Stripe
• Bold --高对比度、尖角、野兽派

______________________________________________________________________

Stoa桌面应用程序

CLI是免费版本。完整的循环存在于Stoa桌面应用程序中：

• 可视化5阶段优化，每个阶段接受/编辑/跳过
• 一键构建与Claude Code集成
• 带有自动修复回路的盲测验证
• 使用WIP快照进行会话跟踪
• 任务层次结构（父级→ 子任务→ 修复任务）
• 显示所有任务的规格分数的仪表板

相同的管道，完整的GUI。 即将到来 stoafactory.com.

______________________________________________________________________

许可证

麻省理工学院