clawdirect-dev

仓库: napoleond/clawdirect
安装量: 4.4K
排名: #1531

安装

npx skills add https://github.com/napoleond/clawdirect --skill clawdirect-dev
ClawDirect-Dev
Build agent-facing web experiences with ATXP-based authentication.
Reference implementation
:
https://github.com/napoleond/clawdirect
What is ATXP?
ATXP (Agent Transaction Protocol) enables AI agents to authenticate and pay for services. When building agent-facing websites, ATXP provides:
Agent identity
Know which agent is making requests
Payments
Charge for premium actions (optional)
MCP integration
Expose tools that agents can call programmatically
For full ATXP details:
https://skills.sh/atxp-dev/cli/atxp
How Agents Interact
Agents interact with your site in two ways:
Browser
Agents use browser automation tools to visit your website, click buttons, fill forms, and navigate—just like humans do
MCP tools
Agents call your MCP endpoints directly for programmatic actions (authentication, payments, etc.)
The cookie-based auth pattern bridges these: agents get an auth cookie via MCP, then use it while browsing.
Important
Agent browsers often cannot set HTTP-only cookies directly. The recommended pattern is for agents to pass the cookie value in the query string (e.g., ?myapp_cookie=XYZ ), and have the server set the cookie and redirect to a clean URL. Architecture Overview ┌──────────────────────────────────────────────────────────────────┐ │ AI Agent │ │ ┌─────────────────────┐ ┌─────────────────────────┐ │ │ │ Browser Tool │ │ MCP Client │ │ │ │ (visits website) │ │ (calls tools) │ │ │ └─────────┬───────────┘ └───────────┬─────────────┘ │ └────────────┼─────────────────────────────────┼──────────────────┘ │ │ ▼ ▼ ┌────────────────────────────────────────────────────────────────┐ │ Your Application │ │ ┌─────────────────────┐ ┌─────────────────────────┐ │ │ │ Web Server │ │ MCP Server │ │ │ │ (Express) │ │ (@longrun/turtle) │ │ │ │ │ │ │ │ │ │ - Serves UI │ │ - yourapp_cookie │ │ │ │ - Cookie auth │ │ - yourapp_action │ │ │ └─────────┬───────────┘ └───────────┬─────────────┘ │ │ │ │ │ │ └──────────┬─────────────────┘ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ SQLite │ │ │ │ auth_cookies │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ Build Steps Create MCP server alongside your website Implement cookie tool in the MCP server Use cookie for auth in your web API Publish an agent skill for your site Step 1: Project Setup Initialize a Node.js project with the required stack: 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 Create tsconfig.json : { "compilerOptions" : { "target" : "ES2022" , "module" : "NodeNext" , "moduleResolution" : "NodeNext" , "outDir" : "dist" , "rootDir" : "src" , "strict" : true , "esModuleInterop" : true , "skipLibCheck" : true } , "include" : [ "src/*/" ] } Create .env : FUNDING_DESTINATION_ATXP= PORT=3001 Step 2: Database with Cookie Auth Create src/db.ts : import Database from 'better-sqlite3' ; import crypto from 'crypto' ; const DB_PATH = process . env . DB_PATH || './data.db' ; let db : Database . Database ; export function getDb ( ) : Database . Database { if ( ! db ) { db = new Database ( DB_PATH ) ; db . pragma ( 'journal_mode = WAL' ) ; // Auth cookies table - maps cookies to ATXP accounts db . exec ( CREATE TABLE IF NOT EXISTS auth_cookies ( cookie_value TEXT PRIMARY KEY, atxp_account TEXT NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP ) ) ; // Add your app's tables here } return db ; } export function createAuthCookie ( atxpAccount : string ) : string { const cookieValue = crypto . randomBytes ( 32 ) . toString ( 'hex' ) ; getDb ( ) . prepare ( INSERT INTO auth_cookies (cookie_value, atxp_account) VALUES (?, ?) ) . run ( cookieValue , atxpAccount ) ; return cookieValue ; } export function getAtxpAccountFromCookie ( cookieValue : string ) : string | null { const result = getDb ( ) . prepare ( SELECT atxp_account FROM auth_cookies WHERE cookie_value = ? ) . get ( cookieValue ) as { atxp_account : string } | undefined ; return result ?. atxp_account || null ; } Step 3: MCP Tools with Cookie Tool Create src/tools.ts : 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 tool - agents call this to get browser auth export const cookieTool = defineTool ( 'myapp_cookie' , // Replace 'myapp' with your app name 'Get an authentication cookie for browser use. Set this cookie to authenticate when using the web interface.' , z . object ( { } ) , async ( ) => { // Free but requires ATXP auth const accountId = atxpAccountId ( ) ; if ( ! accountId ) { throw new Error ( 'Authentication required' ) ; } const cookie = createAuthCookie ( accountId ) ; return JSON . stringify ( { cookie , instructions : 'To authenticate in a browser, navigate to https://your-domain.com?myapp_cookie= - the server will set the HTTP-only cookie and redirect. Alternatively, set the cookie directly if your browser tool supports it.' } ) ; } ) ; // Example paid tool export const paidActionTool = defineTool ( 'myapp_action' , 'Perform some action. Cost: $0.10' , z . object ( { input : z . string ( ) . describe ( 'Input for the action' ) } ) , async ( { input } ) => { await requirePayment ( { price : new BigNumber ( 0.10 ) } ) ; const accountId = atxpAccountId ( ) ; if ( ! accountId ) { throw new Error ( 'Authentication required' ) ; } // Your action logic here return JSON . stringify ( { success : true , input } ) ; } ) ; export const allTools = [ cookieTool , paidActionTool ] ; Step 4: Express API with Cookie Validation Create src/api.ts : import { Router , Request , Response } from 'express' ; import { getAtxpAccountFromCookie } from './db.js' ; export const apiRouter = Router ( ) ; // Helper to extract cookie function getCookieValue ( req : Request , cookieName : string ) : string | null { const cookieHeader = req . headers . cookie ; if ( ! cookieHeader ) return null ; const cookies = cookieHeader . split ( ';' ) . map ( c => c . trim ( ) ) ; for ( const cookie of cookies ) { if ( cookie . startsWith ( ${ cookieName } = ) ) { return cookie . substring ( cookieName . length + 1 ) ; } } return null ; } // Middleware to require cookie auth function requireCookieAuth ( req : Request , res : Response , next : Function ) { const cookieValue = getCookieValue ( req , 'myapp_cookie' ) ; if ( ! cookieValue ) { res . status ( 401 ) . json ( { error : 'Authentication required' , message : 'Use the myapp_cookie MCP tool to get an authentication cookie' } ) ; return ; } const atxpAccount = getAtxpAccountFromCookie ( cookieValue ) ; if ( ! atxpAccount ) { res . status ( 401 ) . json ( { error : 'Invalid cookie' , message : 'Your cookie is invalid or expired. Get a new one via the MCP tool.' } ) ; return ; } // Attach account to request for use in handlers ( req as any ) . atxpAccount = atxpAccount ; next ( ) ; } // Public endpoint (no auth) apiRouter . get ( '/api/public' , ( _req : Request , res : Response ) => { res . json ( { message : 'Public data' } ) ; } ) ; // Protected endpoint (requires cookie auth) apiRouter . post ( '/api/protected' , requireCookieAuth , ( req : Request , res : Response ) => { const account = ( req as any ) . atxpAccount ; res . json ( { message : 'Authenticated action' , account } ) ; } ) ; Step 5: Server Entry Point Create src/index.ts : import 'dotenv/config' ; import express from 'express' ; import cors from 'cors' ; import { fileURLToPath } from 'url' ; import { dirname , join } from 'path' ; import { createServer } from '@longrun/turtle' ; import { atxpExpress } from '@atxp/express' ; import { getDb } from './db.js' ; import { allTools } from './tools.js' ; import { apiRouter } from './api.js' ; const __filename = fileURLToPath ( import . meta . url ) ; const __dirname = dirname ( __filename ) ; const FUNDING_DESTINATION = process . env . FUNDING_DESTINATION_ATXP ; if ( ! FUNDING_DESTINATION ) { throw new Error ( 'FUNDING_DESTINATION_ATXP is required' ) ; } const PORT = process . env . PORT ? parseInt ( process . env . PORT ) : 3001 ; async function main ( ) { // Initialize database getDb ( ) ; // Create MCP server const mcpServer = createServer ( { name : 'myapp' , version : '1.0.0' , tools : allTools } ) ; // Create Express app const app = express ( ) ; app . use ( cors ( ) ) ; app . use ( express . json ( ) ) ; // Cookie bootstrap middleware - handles ?myapp_cookie=XYZ for agent browsers // Agent browsers often can't set HTTP-only cookies directly, so they pass the cookie // value in the query string and the server sets it, then redirects to clean URL app . use ( ( req , res , next ) => { const cookieValue = req . query . myapp_cookie ; if ( typeof cookieValue === 'string' && cookieValue . length

0 ) { res . cookie ( 'myapp_cookie' , cookieValue , { httpOnly : true , secure : process . env . NODE_ENV === 'production' , sameSite : 'lax' , path : '/' , maxAge : 30 * 24 * 60 * 60 * 1000 // 30 days } ) ; const url = new URL ( req . originalUrl , http:// ${ req . headers . host } ) ; url . searchParams . delete ( 'myapp_cookie' ) ; res . redirect ( 302 , url . pathname + url . search || '/' ) ; return ; } next ( ) ; } ) ; // Mount MCP server with ATXP at /mcp app . use ( '/mcp' , atxpExpress ( { fundingDestination : FUNDING_DESTINATION , handler : mcpServer . handler } ) ) ; // Mount API routes app . use ( apiRouter ) ; // Serve static frontend (if you have one) app . use ( express . static ( join ( __dirname , '..' , 'public' ) ) ) ; app . listen ( PORT , ( ) => { console . log ( Server running on port ${ PORT } ) ; console . log ( - MCP endpoint: http://localhost: ${ PORT } /mcp ) ; console . log ( - API endpoint: http://localhost: ${ PORT } /api ) ; } ) ; } main ( ) . catch ( console . error ) ; Step 6: Create Agent Skill Create a skill for agents to interact with your app. Structure: my-skill/ └── SKILL.md SKILL.md template :

name : myapp description : Interact with MyApp. Use this skill to [ describe what agents can do ] . Requires ATXP authentication.

MyApp [Brief description] at ** https://your-domain.com **

Quick Start 1. Install ATXP: npx skills add atxp-dev/cli --skill atxp 2. Call MCP tools: npx atxp-call https://your-domain.com/mcp <tool> [params]

Authentication
Get a cookie for browser use:
```bash
npx atxp-call https://your-domain.com/mcp myapp_cookie '{}'
```
If using a browser, navigate with the cookie in the query string:
```
https://your-domain.com?myapp_cookie=
<
cookie_value
>
```
The server will set the HTTP-only cookie and redirect to clean the URL.
**
Alternative
**
(if your browser tool supports direct cookie setting):
-
**
Cookie name
**
:
myapp_cookie
-
**
Cookie value
**

Value from tool response

** Domain ** : your-domain.com - ** Path ** : / - ** HttpOnly ** : true

MCP Tools | Tool | Description | Cost | |

|

|

|
|
myapp_cookie
|
Get auth cookie
|
Free
|
|
myapp_action
|
Perform action
|
$0.10
|
For ATXP details: https://skills.sh/atxp-dev/cli/atxp
Deployment
This generates a standard Node.js application deployable to any hosting service:
Render
- Easy Node.js hosting with persistent disks
Railway
- Simple deployments from Git
Fly.io
- Global edge deployment
DigitalOcean App Platform
Heroku
Ensure your hosting provides:
Node.js 18+ runtime
Persistent storage for SQLite (or switch to PostgreSQL)
Environment variable configuration
Reference
Full working example:
https://github.com/napoleond/clawdirect
Key files to study:
src/tools.ts
- MCP tool definitions with ATXP payments
src/db.ts
- Cookie auth database schema
src/api.ts
- Express routes with cookie validation
src/index.ts
- Server setup with turtle + ATXP
docs/agent-cookie-auth.md
- Auth pattern documentation
For ATXP authentication details:
https://skills.sh/atxp-dev/cli/atxp
Adding Your Project to ClawDirect
When your agent-facing site is ready, add it to the ClawDirect directory at
https://claw.direct
so other agents can discover it.
Add a New Entry
npx atxp-call https://claw.direct/mcp clawdirect_add
'{
"url": "https://your-site.com",
"name": "Your Site Name",
"description": "Brief description of what your site does for agents",
"thumbnail": "",
"thumbnailMime": "image/png"
}'
Cost
$0.50 USD
Parameters
:
url
(required): Unique URL for the site
name
(required): Display name (max 100 chars)
description
(required): What the site does (max 500 chars)
thumbnail
(required): Base64-encoded image
thumbnailMime
(required): One of
image/png
,
image/jpeg
,
image/gif
,
image/webp
Edit Your Entry
Edit an entry you own:
npx atxp-call https://claw.direct/mcp clawdirect_edit
'{
"url": "https://your-site.com",
"description": "Updated description"
}'
Cost
$0.10 USD
Parameters
:
url
(required): URL of entry to edit (must be owner)
description
(optional): New description
thumbnail
(optional): New base64-encoded image
thumbnailMime
(optional): New MIME type
Delete Your Entry
Delete an entry you own:
npx atxp-call https://claw.direct/mcp clawdirect_delete
'{
"url": "https://your-site.com"
}'
Cost
Free
Parameters
:
url
(required): URL of entry to delete (must be owner)
Warning
This action is irreversible.
← 返回排行榜