PaperclipOrg
Claude Agent Skill · by Napoleond

Clawdirect Dev

If you're building web apps that AI agents need to interact with, this handles the tricky authentication dance between MCP tools and browser sessions. Agents ca

Install
Terminal · npx
$npx skills add https://github.com/napoleond/clawdirect --skill clawdirect-dev
Works with Paperclip

How Clawdirect Dev fits into a Paperclip company.

Clawdirect Dev drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md500 lines
Expand
---name: clawdirect-devdescription: Build agent-facing web experiences with ATXP-based authentication, following the ClawDirect pattern. Use this skill when building websites that AI agents interact with via MCP tools, implementing cookie-based agent auth, or creating agent skills for web apps. Provides templates using @longrun/turtle, Express, SQLite, and ATXP.--- # 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: 1. **Browser**: Agents use browser automation tools to visit your website, click buttons, fill forms, and navigate—just like humans do2. **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 1. **Create MCP server** alongside your website2. **Implement cookie tool** in the MCP server3. **Use cookie for auth** in your web API4. **Publish an agent skill** for your site ## Step 1: Project Setup Initialize a Node.js project with the required stack: ```bashmkdir my-agent-app && cd my-agent-appnpm init -ynpm install @longrun/turtle @atxp/server @atxp/express better-sqlite3 express cors dotenv zodnpm install -D typescript @types/node @types/express @types/cors @types/better-sqlite3 tsx``` Create `tsconfig.json`:```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=<your_atxp_account>PORT=3001``` ## Step 2: Database with Cookie Auth Create `src/db.ts`: ```typescriptimport 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`: ```typescriptimport { 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 authexport 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=<cookie_value> - the server will set the HTTP-only cookie and redirect. Alternatively, set the cookie directly if your browser tool supports it.'    });  }); // Example paid toolexport 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`: ```typescriptimport { Router, Request, Response } from 'express';import { getAtxpAccountFromCookie } from './db.js'; export const apiRouter = Router(); // Helper to extract cookiefunction 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 authfunction 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`: ```typescriptimport '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**: ```markdown---name: myappdescription: 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: \`\`\`bashnpx 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](https://render.com) - Easy Node.js hosting with persistent disks- [Railway](https://railway.app) - Simple deployments from Git- [Fly.io](https://fly.io) - Global edge deployment- [DigitalOcean App Platform](https://www.digitalocean.com/products/app-platform)- [Heroku](https://heroku.com) 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 ```bashnpx 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": "<base64_encoded_image>",  "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: ```bashnpx 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: ```bashnpx 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.