Run402 MCP (Kychee Com)

run402 — Postgres, storage & deploys for AI agents

  ](https://www.npmjs.com/package/@run402/sdk) ](https://www.npmjs.com/package/run402) ](https://www.npmjs.com/package/run402-mcp) ](https://www.npmjs.com/package/@run402/functions) 

跑步402 为代理提供完整的Postgres数据库、REST API、用户身份验证、内容寻址文件存储、静态网站托管、无服务器功能和图像生成-通过一个调用提供，使用x402 USDC on Base（或Stripe信用）支付。原型层在测试网上是免费的。

这个monorepo可以运送代理可以拾取的每一个表面：

所有五个接口在同一版本中同步发布，并在适当的情况下共享一个类型内核： @run402/sdk.MCP工具、CLI子命令和OpenClaw脚本是SDK调用的精简工具； @run402/functions 是在部署代码中运行的函数内助手。选择适合您运行时的接口。

30秒开始

npm install -g run402
run402 init                                          # creates allowance, requests testnet faucet
run402 tier set prototype                            # free on testnet (verifies x402 setup)
run402 projects provision --name my-app              # → anon_key, service_key, project_id
run402 sites deploy-dir ./dist                       # incremental deploy of a directory → live URL
run402 subdomains claim my-app                       # → https://my-app.run402.com

这是一个真正的Postgres数据库+一个部署的静态站点，由testnet USDC自主支付。

图案

粘贴并转移资产——带有SRI的内容寻址URL

blobs.put() 返回a AssetRef 谁的 scriptTag() / linkTag() / imgTag() 发射器生成带有URL、SRI完整性哈希和现代最佳实践属性的HTML(defer, loading="lazy", decoding="async", crossorigin)已经连线了。URL是内容寻址的(pr- .run402.com/_blob/-.)，通过v1.33 CDN提供，无需失效：

import { run402 } from "@run402/sdk/node";
const r = run402();

const logo  = await r.blobs.put(projectId, "logo.png", { bytes: pngBytes });
const app   = await r.blobs.put(projectId, "app.js",   { content: jsSource });
const style = await r.blobs.put(projectId, "app.css",  { content: css });

const html = `

  ${style.linkTag()}${app.scriptTag({ type: "module" })}
  ${logo.imgTag("Company logo")}

`;

immutable: true 默认情况下，SDK在客户端计算SHA-256，网关返回内容哈希URL，浏览器拒绝执行字节不匹配。没有缓存失效编排，没有等待，没有完整性属性构造。

默认情况下为深色表+暴露清单

您创建的表无法通过访问 /rest/v1/* 直到你在清单上宣布它们。这关闭了“代理创建了一个表，忘记设置RLS，数据泄露”的脚枪。清单是收敛的——应用两次是不行的；在应用程序之间删除的项目将删除其策略、授权、触发器和视图。

cat > manifest.json  process.stderr.write(JSON.stringify(e) + "\n"),
});

进度事件源源不断 onEvent （或CLI中的stderr）统一 DeployEvent v2部署原语中的JSON对象。

CLI：

run402 sites deploy-dir ./dist --project prj_… > result.json 2> events.log

同源web路由——静态站点+功能入口

Deploy-v2路由和静态公共路径是发布资源：它们与同一个站点、函数、迁移、机密和子域原子性地激活 deploy apply.释放静态资产路径，例如 events.html 与浏览器可见的公共静态路径不同，例如 /events.使用 site.public_paths 对于普通的干净静态URL；为函数入口和精确的、方法感知的静态别名保留路由。

{
  "project_id": "prj_...",
  "site": {
    "replace": {
      "index.html": { "data": "fetch('/api/hello')" },
      "events.html": { "data": "
Events
" }
    },
    "public_paths": {
      "mode": "explicit",
      "replace": {
        "/events": { "asset": "events.html", "cache_class": "html" }
      }
    }
  },
  "functions": {
    "replace": {
      "api": {
        "runtime": "node22",
        "source": {
          "data": "export default async function handler(req) { const url = new URL(req.url); return Response.json({ ok: true, path: url.pathname }); }"
        }
      },
      "login": {
        "runtime": "node22",
        "source": { "data": "export default async function handler(req) { return Response.json({ ok: true }); }" }
      }
    }
  },
  "routes": {
    "replace": [
      { "pattern": "/api/*", "methods": ["GET", "POST", "OPTIONS"], "target": { "type": "function", "name": "api" } },
      { "pattern": "/login", "methods": ["POST"], "target": { "type": "function", "name": "login" } }
    ]
  }
}

site.public_paths.mode: "explicit" 仅表示完整 public_paths.replace 表可以作为静态URL直接访问。在该示例中， /events 为发布资产提供服务 events.html，而 /events.html 除非另行声明，否则不公开。 mode: "implicit" 恢复文件名派生的公共可达性，并可以扩大访问范围，因此在确认之前请查看网关警告。

省略 routes 或通过 routes: null 推进基本路线。使用 routes: { "replace": [] } 以清除路由表。路线条目是有序的 replace 列表，而不是路径键控映射。功能目标使用 { "type": "function", "name": "" }静态路由目标仅使用精确的模式和方法 ["GET"] 或 ["GET","HEAD"]，以及 { "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } } 哪里 file 是发布静态资产路径，而不是公共路径、URL、CAS哈希、重写或重定向。将静态路由目标用于方法感知别名，如static GET /login 加功能 POST /login；在显式公共路径模式下，支持资产可以按文件名保持私有。直接的 /functions/v1/:name 调用保持受API-key保护；浏览器路由路径是公共同源入口。

匹配仅是精确或最终前缀通配符。 /admin 和 /admin/ 是精确的尾随斜线等价物； /admin/* 匹配儿童，但不匹配 /admin, /admin/, /admin.css，或 /administrator，因此部署两者 /admin 和 /admin/* 对于路由段根。查询字符串在匹配时被忽略，并保留在处理程序的完整公共文件中 req.url精确路由优于前缀路由；最长前缀获胜；方法兼容的动态路由胜过静态资产。A. POST /login 路由可以与静态共存 GET /login HTML。不安全的方法不匹配返回 405，并且匹配的动态路由故障会失败关闭，而不是退回到静态文件。

路由函数使用Node 22 Fetch Request->Response合约： export default async function handler(req) { ... }. req.method 是浏览器方法，以及 req.url 是托管子域、部署主机和经过验证的自定义域上的完整公共URL。例如，从中派生OAuth回调 new URL("/admin/oauth/google/callback", new URL(req.url).origin).添加多个Cookie headers.append("Set-Cookie", value)；重定向、Cookie和查询字符串被保留。生的 run402.routed_http.v1 信封是内部的；不要针对它编写路由处理程序。

避免路由每个静态文件、默认情况下的宽方法列表、通配符静态路由目标、前导斜线静态文件、目录简写以及每页一个静态路由目标表，这些表会耗尽路由限制。还要注意隐藏直接公共静态路径的通配符函数路由。要处理的警告代码包括 STATIC_ALIAS_SHADOWS_STATIC_PATH, STATIC_ALIAS_RELATIVE_ASSET_RISK, STATIC_ALIAS_DUPLICATE_CANONICAL_URL, STATIC_ALIAS_EXTENSIONLESS_NON_HTML，以及 STATIC_ALIAS_TABLE_NEAR_LIMIT检查活动路线， static_public_paths，并解决诊断问题，以区分路线模式和倒车 asset_path.

使用URL优先的CLI或MCP/SDK等效工具诊断公共URL：

run402 deploy diagnose --project prj_123 https://example.com/events --method GET
run402 deploy resolve --project prj_123 --url https://example.com/events?utm=x#hero --method GET
run402 deploy resolve --project prj_123 --host example.com --path /events --method GET

deploy_diagnose_url 和 r.deploy.resolve({ project, url, method: "GET" }) 返回 would_serve, diagnostic_status, match，规范化请求数据、警告、全分辨率JSON和下一步。当返回时， asset_path, reachability_authority，以及 direct 解释哪个发布资产支持公共URL，以及可达性是否来自隐式文件路径模式，显式 site.public_paths，或仅路由静态别名。稳定的主机诊断可能还包括 authorization_result, cas_object (sha256, exists, expected_size, actual_size)，主机名特定 response_variant，以及路由/静态字段，例如 allow, route_pattern, target_type, target_name，以及 target_file已知 match 文字是 host_missing, manifest_missing, active_release_missing, unsupported_manifest_version, path_error, none, static_exact, static_index, spa_fallback, spa_fallback_missing, route_function, route_static_alias，以及 route_method_miss；保留未知的未来字符串。已知 authorization_result 值包括 authorized, not_public, not_applicable, manifest_missing, target_missing, active_release_missing, unsupported_manifest_version, path_error, missing_cas_object, unfinalized_or_deleting_cas_object, size_mismatch，以及 unauthorized_cas_object已知 fallback_state 值包括 active_release_missing, unsupported_manifest_version，以及 negative_cache_hit；保留未知的未来字符串。 result 是诊断体状态，而不是SDK调用的HTTP状态，因此主机未命中仍然可以是成功的CLI/MCP/SDK调用 would_serve: false.不要将解析/诊断视为获取、缓存清除或缓存策略预言机；应检查路线方法失误 allow和CAS授权/运行状况故障应检查或重新部署受影响的静态资产。结构化JSON字段上的分支，例如 cache_class 并保留未知的缓存类。

发布可观察性揭示了稳定的资产身份和公共可达性。库存包括 release_generation, static_manifest_sha256，可以为null static_manifest_metadata (file_count, total_bytes, cache_classes, cache_class_sources, spa_fallback)，以及 static_public_paths[] 当返回时。 site.paths 列表发布静态资产； static_public_paths[] 列出浏览器可见的公共路径 public_path, asset_path, reachability_authority, direct、缓存类和内容类型。计划并发布差异暴露 static_assets 计数器：未更改/更改/添加/删除， newly_uploaded_cas_bytes, reused_cas_bytes, deployment_copy_bytes_eliminated, legacy_immutable_warnings, previous_immutable_failures，以及 cas_authorization_failures.

要在以下位置分支的运行时路由失败代码： ROUTE_MANIFEST_LOAD_FAILED （清单/传播）， ROUTED_INVOKE_WORKER_SECRET_MISSING （自定义域Worker机密）， ROUTED_INVOKE_AUTH_FAILED （内部调用签名）， ROUTED_ROUTE_STALE （所选路线未通过发布重新验证）， ROUTE_METHOD_NOT_ALLOWED （方法不匹配），以及 ROUTED_RESPONSE_TOO_LARGE （机身超过6 MiB）。

GitHub Actions OIDC部署——链接一次，使用相同的CLI部署

对于仓库驱动的部署，Run402不需要GitHub secrets中的服务密钥或允许文件。运行一次本地链接命令：

run402 ci link github --project prj_... --manifest run402.deploy.json
# Optional route authority for CI route declarations:
run402 ci link github --project prj_... --manifest run402.deploy.json --route-scope /admin --route-scope /api/*

这创建了一个部署范围 /ci/v1/* 绑定并编写授权的工作流 id-token: write，签出repo，并运行现有的部署原语：

permissions:
  contents: read
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to run402
        run: npx --yes run402@1.60.0 deploy apply --manifest 'run402.deploy.json' --project 'prj_...'

CI部署有意缩小范围： site, functions, database，缺席/当前 base，并且仅当绑定具有覆盖时才进行路由声明 --route-scope 模式。没有航线范围，CI无法发货 routes。在本地许可支持的部署中保留机密、域、子域、检查、非当前基础和更广泛的信任更改。如果网关返回 CI_ROUTE_SCOPE_DENIED，重新链接到精确的范围，如 /admin 或最终通配符范围，如 /api/*，或在本地部署。使用管理绑定 run402 ci list 和 run402 ci revoke.

函数内助手——调用者上下文与BYPASSRLS

在已部署的函数中，从导入 @run402/functions两个不同的DB客户端保持RLS干净：

import { db, adminDb, getUser, email, ai } from "@run402/functions";

export default async (req: Request) => {
  const user = await getUser(req);
  if (!user) return new Response("unauthorized", { status: 401 });

  // Caller-context — Authorization header is forwarded; RLS evaluates against the caller's role.
  const mine = await db(req).from("items").select("*").eq("user_id", user.id);

  // BYPASSRLS — for platform-authored writes (audit logs, cron cleanup, webhook handlers).
  await adminDb().from("audit").insert({ event: "items_read", user_id: user.id });

  // Send mail from the project's mailbox — discovers it automatically.
  if (mine.length === 0) {
    await email.send({ to: user.email, subject: "Welcome", html: "
hi
" });
  }

  return Response.json(mine);
};

adminDb().sql(query, params?) 运行原始参数化SQL并始终绕过RLS。它返回一个平面 Promise[]> （只有行，没有信封）：

import { adminDb, getUser } from "@run402/functions";

export default async (req: Request) => {
  const user = await getUser(req);
  if (!user) return new Response("unauthorized", { status: 401 });

  const rows = await adminDb().sql(
    "SELECT count(*)::int AS n FROM items WHERE user_id = $1",
    [user.id],
  );
  const n = (rows[0]?.n as number | undefined) ?? 0;
  return Response.json({ count: n });
};

@run402/functions 自动捆绑到部署的代码中；在编辑器中安装它，以实现完整的TypeScript自动补全（在构建时也适用于静态站点生成 RUN402_SERVICE_KEY + RUN402_PROJECT_ID 设置）。

完全从函数外部调用 （生 curl/fetch 从CI脚本、bash引导程序、非TS运行时）——服务密钥写入转到 /admin/v1/rest/，不 /rest/v1/*网关403上的服务角色令牌 /rest/v1/* 因此，泄露的密钥不能悄无声息地绕过RLS，这意味着 curl ... > /dev/null 反对错误的道路看起来像是成功，但什么也写不出来。SQL形状的管理工作使用 POST /projects/v1/admin/:id/sql （或 run402 projects sql).

curl -X POST https://api.run402.com/admin/v1/rest/audit \
  -H "Authorization: Bearer $RUN402_SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"seed","ts":"2026-04-30"}'

SDK-- @run402/sdk

npm install @run402/sdk

两个入口点：

• @run402/sdk --同构。带上你自己的 CredentialsProvider （会话令牌填充程序、远程保管库、解析项目密钥+身份验证头的任何东西）。适用于Node 22、Deno、Bun、V8隔离。
• @run402/sdk/node --仅节点方便。倒像 ~/.config/run402/projects.json，从当地津贴中支付x402，暴露 sites.deployDir(...), fileSetFromDir(...)，并键入部署清单帮助程序(loadDeployManifest, normalizeDeployManifest).

import { run402 } from "@run402/sdk/node";

const r = run402();
const project = await r.projects.provision({ tier: "prototype" });
await r.blobs.put(project.project_id, "hello.txt", { content: "hi" });

20个命名空间： projects, deploy, ci, sites, blobs, functions, secrets, subdomains, domains, email (+ webhooks), senderDomain, auth, apps, tier, billing, contracts, ai, allowance, service, admin.每个操作都会抛出一个类型 Run402Error 故障子类： PaymentRequired, ProjectNotFound, Unauthorized, ApiError, NetworkError, LocalError, Run402DeployError. deploy.apply() 自动重新规划安全当前基地 BASE_RELEASE_CONFLICT 种族和排放 deploy.retry 进度事件。看 sdk/README.md.

CLI-- run402

npm install -g run402

每个子命令都会将JSON打印到stdout，将JSON错误打印到stderr，成功时退出0，失败时退出1——这是为代理shell设计的，而不是为人类设计的。完整参考： cli/llms-cli.txt （也在 ).

run402 init                              # one-shot allowance + faucet + tier check
run402 status                            # account snapshot (allowance, balance, tier, projects)
run402 projects provision --name my-app
run402 projects sql  "CREATE TABLE …"
run402 projects validate-expose  --file manifest.json
run402 projects apply-expose  --file manifest.json
run402 sites deploy-dir ./dist
run402 deploy release active --project   # inspect current-live release inventory
run402 deploy diagnose --project  https://example.com/events --method GET
run402 functions deploy   --file fn.ts
run402 ci link github --project        # GitHub Actions OIDC deploy binding (--route-scope for CI routes)
run402 blob put ./asset.png --immutable
run402 blob diagnose                # inspect live CDN state for a public URL
run402 cdn wait-fresh  --sha   # poll until a mutable URL serves the new SHA

活动项目具有粘性： run402 projects use 使 ` 每个后续操作的默认值 `-使用子命令，因此大多数命令都可以在没有它的情况下工作。

MCP服务器-- run402-mcp

npx -y run402-mcp                        # standalone test

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

光标

添加 .cursor/mcp.json:

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

克莱恩

添加到您的Cline MCP设置中：

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

克劳德代码

claude mcp add run402 -- npx -y run402-mcp

OpenClaw技能

cp -r openclaw ~/.openclaw/skills/run402
cd ~/.openclaw/skills/run402/scripts && npm install

每个脚本都从以下位置重新导出 cli/lib/*.mjs --OpenClaw命令界面在构造上与CLI命令界面相同。看 openclaw/README.md.

MCP工具

完整的MCP表面——每个工具都是SDK调用上的薄垫片。

数据库

Blob存储（内容寻址CDN）

网站和子域名

CI/OIDC绑定

功能和秘密

认证和电子邮件

AI助手

应用市场

层级和计费

KMS合约钱包（链上签名）

津贴和账户

服务状态（无身份验证）

配置

当地州居住地址：

• ~/.config/run402/projects.json (0600) — { projects: { : { anon_key, service_key, tier, lease_expires_at } } }
• ~/.config/run402/allowance.json (0600)--用于x402签名的钱包

anon_key 和 service_key 没有到期日——租约执行发生在服务器端。通过删除项目并重新配置来旋转它们。

发展

npm run build           # builds core/, sdk/, functions/, then the MCP server
npm test                # SKILL + sync + unit tests
npm run test:e2e        # 47 CLI end-to-end tests
npm run test:sync       # checks MCP/CLI/OpenClaw/SDK stay in sync
npm run test:skill      # validates SKILL.md frontmatter + body

架构：每个工具/子命令/技能脚本都是一个薄薄的垫片 @run402/sdk 电话。 core/ 保存由SDK的Node提供者包装的仅Node文件系统原语（密钥库、允许、SIWE签名）。看 CLAUDE.md 完整布局。

链接

• 网状物：
• API文档（HTTP）： ·
• CLI文档：
• 状态：
• 健康：

简体中文

许可证

麻省理工学院