ClawDirect-Dev

构建基于ATXP认证的面向代理的Web体验。

参考实现: https://github.com/napoleond/clawdirect

什么是ATXP？

ATXP（代理交易协议）使AI代理能够进行身份认证并为服务付费。在构建面向代理的网站时，ATXP提供：

• - 代理身份：识别哪个代理正在发起请求
• 支付：对高级操作收费（可选）
• MCP集成：暴露代理可以编程调用的工具

完整ATXP详情：https://skills.sh/atxp-dev/cli/atxp

代理如何交互

代理通过两种方式与您的网站交互：

1. 1. 浏览器：代理使用浏览器自动化工具访问您的网站、点击按钮、填写表单和导航——就像人类一样
2. MCP工具：代理直接调用您的MCP端点进行编程操作（认证、支付等）

基于Cookie的认证模式连接了这两种方式：代理通过MCP获取认证Cookie，然后在浏览时使用它。

重要提示：代理浏览器通常无法直接设置HTTP-only Cookie。推荐模式是代理在查询字符串中传递Cookie值（例如，?myapp_cookie=XYZ），然后由服务器设置Cookie并重定向到干净的URL。

架构概览

┌──────────────────────────────────────────────────────────────────┐
│ AI代理 │
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
│ │ 浏览器工具 │ │ MCP客户端 │ │
│ │ (访问网站) │ │ (调用工具) │ │
│ └─────────┬───────────┘ └───────────┬─────────────┘ │
└────────────┼─────────────────────────────────┼──────────────────┘
│ │
▼ ▼
┌────────────────────────────────────────────────────────────────┐
│ 您的应用程序 │
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
│ │ Web服务器 │ │ MCP服务器 │ │
│ │ (Express) │ │ (@longrun/turtle) │ │
│ │ │ │ │ │
│ │ - 提供UI │ │ - yourapp_cookie │ │
│ │ - Cookie认证 │ │ - yourapp_action │ │
│ └─────────┬───────────┘ └───────────┬─────────────┘ │
│ │ │ │
│ └──────────┬─────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ SQLite │ │
│ │ auth_cookies │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

构建步骤

1. 1. 创建MCP服务器，与您的网站并行
2. 在MCP服务器中实现Cookie工具
3. 在您的Web API中使用Cookie进行认证
4. 为您的网站发布代理技能

步骤1：项目设置

使用所需技术栈初始化Node.js项目：

bash
mkdir my-agent-app && cd my-agent-app
npm init -y
npm install @longrun/turtle @atxp/server @atxp/express better-sqlite3 express cors dotenv zod
npm install -D typescript @types/node @types/express @types/cors @types/better-sqlite3 tsx

创建 tsconfig.json：
json
{
compilerOptions: {
target: ES2022,
module: NodeNext,
moduleResolution: NodeNext,
outDir: dist,
rootDir: src,
strict: true,
esModuleInterop: true,
skipLibCheck: true
},
include: [src//*]
}

创建 .env：

FUNDINGDESTINATIONATXP=<您的atxp账户>
PORT=3001

步骤2：带Cookie认证的数据库

创建 src/db.ts：

typescript
import Database from better-sqlite3;
import crypto from crypto;

const DBPATH = process.env.DBPATH || ./data.db;
let db: Database.Database;

export function getDb(): Database.Database {
if (!db) {
db = new Database(DB_PATH);
db.pragma(journal_mode = WAL);

// 认证Cookie表 - 将Cookie映射到ATXP账户
db.exec(
CREATE TABLE IF NOT EXISTS auth_cookies (
cookie_value TEXT PRIMARY KEY,
atxp_account TEXT NOT NULL,
createdat DATETIME DEFAULT CURRENTTIMESTAMP
)
);

// 在此添加您的应用表
}
return db;
}

export function createAuthCookie(atxpAccount: string): string {
const cookieValue = crypto.randomBytes(32).toString(hex);
getDb().prepare(
INSERT INTO authcookies (cookievalue, atxp_account)
VALUES (?, ?)
).run(cookieValue, atxpAccount);
return cookieValue;
}

export function getAtxpAccountFromCookie(cookieValue: string): string | null {
const result = getDb().prepare(
SELECT atxpaccount FROM authcookies WHERE cookie_value = ?
).get(cookieValue) as { atxp_account: string } | undefined;
return result?.atxp_account || null;
}

步骤3：带Cookie工具的MCP工具

创建 src/tools.ts：

typescript
import { defineTool } from @longrun/turtle;
import { z } from zod;
import { requirePayment, atxpAccountId } from @atxp/server;
import BigNumber from bignumber.js;
import { createAuthCookie } from ./db.js;

// Cookie工具 - 代理调用此工具获取浏览器认证
export const cookieTool = defineTool(
myapp_cookie, // 将myapp替换为您的应用名称
获取用于浏览器使用的认证Cookie。设置此Cookie以在使用Web界面时进行认证。,
z.object({}),
async () => {
// 免费但需要ATXP认证
const accountId = atxpAccountId();
if (!accountId) {
throw new Error(需要认证);
}

const cookie = createAuthCookie(accountId);

return JSON.stringify({
cookie,
instructions: 要在浏览器中认证，请导航到 https://your-domain.com?myappcookie=value> - 服务器将设置HTTP-only Cookie并重定向。或者，如果您的浏览器工具支持，可以直接设置Cookie。
});
}
);