Homespun

@homespunapps/mcp

面向 Homespun 的轻量级 stdio Model Context Protocol 服务。它让任何 MCP 客户端（Claude Desktop、Cursor、Windsurf、Cline 或你自己的宿主）都能通过一次调用部署真正的多用户 Web 应用，并在之后持续操作其数据：应用托管在专属 URL 上，包含魔法链接身份验证、按角色设置权限的共享实时数据库、邮件通知和文件附件。

它是一个封装层，而非重新实现：所有中继 I/O 都通过 @homespunapps/core 完成，并且与 homespun CLI 共用配置（~/.config/homespun/config.json），因此 CLI 和此服务使用同一 Agent 身份。

运行时要求：Node.js >= 20

二进制文件为 homespun-mcp。它通过 stdio 使用 MCP，旨在由 MCP 宿主启动，而非交互式运行。

快速开始

无需全局安装：将 MCP 客户端指向 npx @homespunapps/mcp 即可。首次使用时，如果未配置 API 密钥，服务会自动在托管中继上注册一个新 Agent，并将密钥保存到共享的 CLI 存储中；无需进行其他设置。

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"]
    }
  }
}

若要固定使用现有 Agent 密钥而不是自动注册，请添加 env 块：

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": { "HOMESPUN_API_KEY": "hs_..." }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": { "HOMESPUN_API_KEY": "hs_..." }
    }
  }
}

通用 MCP 宿主

任何支持 command + args + env 的客户端都可以采用相同方式配置：

{
  "mcpServers": {
    "homespun": {
      "command": "npx",
      "args": ["-y", "@homespunapps/mcp"],
      "env": {
        "HOMESPUN_URL": "https://homespun.dev",
        "HOMESPUN_API_KEY": "hs_..."
      }
    }
  }
}

如果你更愿意全局安装（npm i -g @homespunapps/mcp），请使用 "command": "homespun-mcp"，无需设置 args。

配置

所有环境变量均为可选；默认配置面向托管中继，并会在首次使用时自动注册。

变量	默认值	用途
HOMESPUN_URL	https://homespun.dev	中继基础 URL。设置此项可指向其他中继。
HOMESPUN_API_KEY	(自动注册)	Agent API 密钥。如果未设置，服务会在首次使用时注册一个 Agent，并将密钥保存到 ~/.config/homespun/config.json（与 CLI 共用）。
HOMESPUN_TOKEN	(无)	HOMESPUN_API_KEY 的别名（适用于将密钥命名为 *_TOKEN 的宿主）。如果两者均已设置，则以 HOMESPUN_API_KEY 为准。
HOMESPUN_AGENT_NAME	homespun-mcp	自动注册的 Agent 的显示名称。
HOMESPUN_REGISTER_SECRET	(无)	注册密钥，仅用于运行 REGISTRATION_MODE=secret 的中继。

配置优先级与 CLI 一致：环境变量优先于已保存的配置，未设置时则回退到默认中继 URL。

工具

此服务与 homespun CLI 完全一致：CLI 提供的所有功能都可以在此使用。

MCP 工具采用请求/响应模式，因此没有长期运行的“监视”。若要查看变化，请使用上一次调用返回的游标轮询 get_feed_events（传入 wait 可进行长轮询，范围为 0 到 30 秒）；若要监视某个集合，请使用上一次返回的 next_cursor 作为 since，再次调用 list_rows。每个工具的描述都为模型说明了相应模式。

为保持工具列表精简（扁平列出 50 多个工具会膨胀客户端上下文并降低选择质量），高频路径上的名词仍作为独立工具，而包含多个动词的管理类名词则各自合并为一个工具，并要求提供 action 枚举值。

热路径（离散）工具

工具	功能
deploy_app	部署一个 v2 应用：由 HTML 文档和功能清单组成，并托管在专属 URL 上。省略 app_id 可创建应用；传入 app_id 可原地重新部署（URL、数据和成员均保持不变）。接受 html 或 html_path，以及可选的 assets、visibility、slug、dry_run、force。
list_rows	列出集合中的行。也可用于轮询集合的当前状态：将之前的 next_cursor 作为 since 传入。
get_row	按 key 获取一行（使用专用中继路由，而不是在客户端扫描）。
add_row	创建一行；如果 key 已存在，则返回现有行（deduped: true）；如果集合的 read 列表未授权你读取该行，则返回 row_not_found。唯一用于创建的动词。
update_row	替换现有行的 data。可选的 if_match 乐观锁。
delete_row	软删除一行。可选的 if_match。
get_feed_events	轮询应用的变更信息流，获取任何写入者（无论是人还是 Agent）对行的创建、更新和删除事件。可选的 wait（0-30 秒）用于长轮询。

合并工具（一个工具，必需的 action）

工具	操作
apps	list · show · update · share_link_rotate · delete · wake · domain_set · domain_status · domain_remove
members	add · list · set_role · remove · roles
grants	mint · list · revoke
ingest	list · rotate · set_signing_secret · clear_signing_secret
attachments	upload · fetch · presign · finalize · download · show · list · delete · mint_token · revoke_token · list_tokens
taste	get · set · clear
key	list · mint · revoke
feedback	create · list
agent	whoami · claim · logout
community	publish · unpublish · get_config_contract · install · list_pending · get_submission · approve · reject · set_trust_level
publisher	claim · get · update
review	create · respond · report · remove · unhold

单一用途工具

工具	功能
get_skill	获取中继自动更新的指南（无需身份验证），以自学工作流。

附件接收并返回文件路径：upload 读取绝对路径 file_path；download 写入绝对路径 out_path（若省略，则返回 base64）。对于实际媒体，使用 presign，然后执行 PUT，再调用 finalize，即可避免通过工具调用传输字节。

一种数据原语。 应用存储的所有内容都是一个集合：一组有名称、可变且可查询的行，每行都有一个 key、一个 data 载荷、一个乐观锁 version 和一个 author。每次写入也都会记录到应用的有序变更信息流中。若要创建日志（例如审计跟踪或提交记录），而非可变状态，可在清单中将集合声明为 appendOnly: true。

未公开的功能（及原因）

• CLI 的 config show 已由 agent → whoami 取代（显示解析出的中继 URL、活动配置文件以及是否已设置密钥；不显示机密）。
• agent register 不是工具。服务器会在首次使用时自动注册，并与 CLI 共用密钥存储；之后可通过 agent → claim 将其绑定到某个人。
• demo（交互式终端导览）和 CLI 自动更新程序属于终端功能，Agent 不会用到，因此省略。

典型流程

1. 使用你的 HTML 和 x-homespun-manifest 调用 deploy_app，在清单中声明应用的集合，以及哪些角色可以读取、写入和删除各个集合。返回 { app_id, url, ... }。
2. 将 url 提供给所有者，并通过 members（action: add）邀请其他人。
3. 在循环中调用 get_feed_events 并设置 wait: 25，将之前的 cursor 作为 since 传入，以查看人们的操作。
4. 使用 list_rows / add_row / update_row 读取和写入相同的数据；再次调用 deploy_app 并传入 app_id，即可发布更改。

MCP 注册表

server.json（位于此软件包中）包含官方 MCP 注册表的元数据。发布到该注册表是维护者的后续步骤。

许可证

MIT，详见 LICENSE。