clawdentials-mcp 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# Clawdentials MCP Server
+
+Escrow and reputation infrastructure for AI agent commerce.
+
+## Installation
+
+```bash
+npm install clawdentials-mcp
+```
+
+Or clone and build locally:
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clawdentials": {
+      "command": "node",
+      "args": ["/path/to/clawdentials/mcp-server/dist/index.js"],
+      "env": {
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `GOOGLE_APPLICATION_CREDENTIALS` - Path to Firebase service account JSON
+
+## Tools
+
+### escrow_create
+
+Lock funds for a task.
+
+**Input:**
+- `taskDescription` (string) - What needs to be done
+- `amount` (number) - Amount to escrow
+- `currency` (string) - USD, USDC, or BTC
+- `providerAgentId` (string) - Agent who will do the work
+- `clientAgentId` (string) - Agent creating the escrow
+
+**Output:**
+- `escrowId` - Unique identifier for the escrow
+- `status` - Current status (pending)
+
+### escrow_complete
+
+Release funds after task completion.
+
+**Input:**
+- `escrowId` (string) - The escrow to complete
+- `proofOfWork` (string) - Evidence the task was done
+
+**Output:**
+- `success` - Whether funds were released
+- `escrow` - Updated escrow details
+
+### escrow_status
+
+Check the state of an escrow.
+
+**Input:**
+- `escrowId` (string) - The escrow to check
+
+**Output:**
+- `escrow` - Full escrow details including status
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Type check
+npm run typecheck
+```
+
+## Firestore Collections
+
+The server uses these Firestore collections:
+
+- `escrows/` - Escrow records
+- `agents/` - Agent profiles and stats
+- `tasks/` - Task history
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { escrowTools } from './tools/index.js';
+import { initFirestore } from './services/firestore.js';
+// Initialize Firestore
+initFirestore();
+// Create MCP server
+const server = new McpServer({
+    name: 'clawdentials',
+    version: '0.1.0',
+});
+// Register escrow_create tool
+server.tool('escrow_create', escrowTools.escrow_create.description, {
+    taskDescription: z.string().describe('Description of the task to be completed'),
+    amount: z.number().positive().describe('Amount to escrow in the specified currency'),
+    currency: z.enum(['USD', 'USDC', 'BTC']).default('USD').describe('Currency for the escrow'),
+    providerAgentId: z.string().describe('ID of the agent who will complete the task'),
+    clientAgentId: z.string().describe('ID of the agent creating the escrow'),
+}, async (args) => {
+    const result = await escrowTools.escrow_create.handler(args);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+});
+// Register escrow_complete tool
+server.tool('escrow_complete', escrowTools.escrow_complete.description, {
+    escrowId: z.string().describe('ID of the escrow to complete'),
+    proofOfWork: z.string().describe('Proof that the task was completed'),
+}, async (args) => {
+    const result = await escrowTools.escrow_complete.handler(args);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+});
+// Register escrow_status tool
+server.tool('escrow_status', escrowTools.escrow_status.description, {
+    escrowId: z.string().describe('ID of the escrow to check'),
+}, async (args) => {
+    const result = await escrowTools.escrow_status.handler(args);
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Clawdentials MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/schemas/index.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+export declare const escrowCreateSchema: z.ZodObject<{
+    taskDescription: z.ZodString;
+    amount: z.ZodNumber;
+    currency: z.ZodDefault<z.ZodEnum<["USD", "USDC", "BTC"]>>;
+    providerAgentId: z.ZodString;
+    clientAgentId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    taskDescription: string;
+    amount: number;
+    currency: "USD" | "USDC" | "BTC";
+    providerAgentId: string;
+    clientAgentId: string;
+}, {
+    taskDescription: string;
+    amount: number;
+    providerAgentId: string;
+    clientAgentId: string;
+    currency?: "USD" | "USDC" | "BTC" | undefined;
+}>;
+export declare const escrowCompleteSchema: z.ZodObject<{
+    escrowId: z.ZodString;
+    proofOfWork: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    escrowId: string;
+    proofOfWork: string;
+}, {
+    escrowId: string;
+    proofOfWork: string;
+}>;
+export declare const escrowStatusSchema: z.ZodObject<{
+    escrowId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    escrowId: string;
+}, {
+    escrowId: string;
+}>;
+export type EscrowCreateInput = z.infer<typeof escrowCreateSchema>;
+export type EscrowCompleteInput = z.infer<typeof escrowCompleteSchema>;
+export type EscrowStatusInput = z.infer<typeof escrowStatusSchema>;

package/dist/schemas/index.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+export const escrowCreateSchema = z.object({
+    taskDescription: z.string().min(1).describe('Description of the task to be completed'),
+    amount: z.number().positive().describe('Amount to escrow in the specified currency'),
+    currency: z.enum(['USD', 'USDC', 'BTC']).default('USD').describe('Currency for the escrow'),
+    providerAgentId: z.string().min(1).describe('ID of the agent who will complete the task'),
+    clientAgentId: z.string().min(1).describe('ID of the agent creating the escrow'),
+});
+export const escrowCompleteSchema = z.object({
+    escrowId: z.string().min(1).describe('ID of the escrow to complete'),
+    proofOfWork: z.string().min(1).describe('Proof that the task was completed (e.g., result summary, link, hash)'),
+});
+export const escrowStatusSchema = z.object({
+    escrowId: z.string().min(1).describe('ID of the escrow to check'),
+});

package/dist/services/firestore.d.ts

@@ -0,0 +1,13 @@
+import { Firestore } from 'firebase-admin/firestore';
+import type { Escrow } from '../types/index.js';
+export declare function initFirestore(): Firestore;
+export declare function getDb(): Firestore;
+export declare const collections: {
+    escrows: () => FirebaseFirestore.CollectionReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+    agents: () => FirebaseFirestore.CollectionReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+    tasks: () => FirebaseFirestore.CollectionReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+    subscriptions: () => FirebaseFirestore.CollectionReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+};
+export declare function createEscrow(data: Omit<Escrow, 'id' | 'createdAt' | 'completedAt' | 'proofOfWork'>): Promise<Escrow>;
+export declare function getEscrow(escrowId: string): Promise<Escrow | null>;
+export declare function completeEscrow(escrowId: string, proofOfWork: string): Promise<Escrow | null>;

package/dist/services/firestore.js

@@ -0,0 +1,99 @@
+import { initializeApp, getApps, applicationDefault } from 'firebase-admin/app';
+import { getFirestore, Timestamp } from 'firebase-admin/firestore';
+let app;
+let db;
+export function initFirestore() {
+    if (getApps().length === 0) {
+        // Use Application Default Credentials (gcloud auth)
+        // This works with: gcloud auth application-default login
+        // Or with GOOGLE_APPLICATION_CREDENTIALS pointing to a service account key
+        app = initializeApp({
+            credential: applicationDefault(),
+            projectId: 'clawdentials',
+        });
+    }
+    else {
+        app = getApps()[0];
+    }
+    db = getFirestore(app);
+    return db;
+}
+export function getDb() {
+    if (!db) {
+        return initFirestore();
+    }
+    return db;
+}
+// Collection references
+export const collections = {
+    escrows: () => getDb().collection('escrows'),
+    agents: () => getDb().collection('agents'),
+    tasks: () => getDb().collection('tasks'),
+    subscriptions: () => getDb().collection('subscriptions'),
+};
+// Escrow operations
+export async function createEscrow(data) {
+    const docRef = collections.escrows().doc();
+    const escrow = {
+        ...data,
+        status: 'pending',
+        createdAt: new Date(),
+        completedAt: null,
+        proofOfWork: null,
+    };
+    await docRef.set({
+        ...escrow,
+        createdAt: Timestamp.fromDate(escrow.createdAt),
+    });
+    return { id: docRef.id, ...escrow };
+}
+export async function getEscrow(escrowId) {
+    const doc = await collections.escrows().doc(escrowId).get();
+    if (!doc.exists) {
+        return null;
+    }
+    const data = doc.data();
+    return {
+        id: doc.id,
+        clientAgentId: data.clientAgentId,
+        providerAgentId: data.providerAgentId,
+        taskDescription: data.taskDescription,
+        amount: data.amount,
+        currency: data.currency,
+        status: data.status,
+        createdAt: data.createdAt.toDate(),
+        completedAt: data.completedAt?.toDate() ?? null,
+        proofOfWork: data.proofOfWork ?? null,
+    };
+}
+export async function completeEscrow(escrowId, proofOfWork) {
+    const escrowRef = collections.escrows().doc(escrowId);
+    const doc = await escrowRef.get();
+    if (!doc.exists) {
+        return null;
+    }
+    const completedAt = new Date();
+    await escrowRef.update({
+        status: 'completed',
+        completedAt: Timestamp.fromDate(completedAt),
+        proofOfWork,
+    });
+    const escrow = await getEscrow(escrowId);
+    // Update agent stats
+    if (escrow) {
+        await updateAgentStats(escrow.providerAgentId, escrow.amount);
+    }
+    return escrow;
+}
+async function updateAgentStats(agentId, amount) {
+    const agentRef = collections.agents().doc(agentId);
+    const doc = await agentRef.get();
+    if (doc.exists) {
+        const data = doc.data();
+        const currentStats = data.stats || { tasksCompleted: 0, totalEarned: 0, successRate: 100, avgCompletionTime: 0 };
+        await agentRef.update({
+            'stats.tasksCompleted': currentStats.tasksCompleted + 1,
+            'stats.totalEarned': currentStats.totalEarned + amount,
+        });
+    }
+}

package/dist/tools/escrow.d.ts

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { type EscrowCreateInput, type EscrowCompleteInput, type EscrowStatusInput } from '../schemas/index.js';
+export declare const escrowTools: {
+    escrow_create: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            taskDescription: z.ZodString;
+            amount: z.ZodNumber;
+            currency: z.ZodDefault<z.ZodEnum<["USD", "USDC", "BTC"]>>;
+            providerAgentId: z.ZodString;
+            clientAgentId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            taskDescription: string;
+            amount: number;
+            currency: "USD" | "USDC" | "BTC";
+            providerAgentId: string;
+            clientAgentId: string;
+        }, {
+            taskDescription: string;
+            amount: number;
+            providerAgentId: string;
+            clientAgentId: string;
+            currency?: "USD" | "USDC" | "BTC" | undefined;
+        }>;
+        handler: (input: EscrowCreateInput) => Promise<{
+            success: boolean;
+            escrowId: string;
+            message: string;
+            escrow: {
+                id: string;
+                amount: number;
+                currency: import("../types/index.js").Currency;
+                status: import("../types/index.js").EscrowStatus;
+                providerAgentId: string;
+                createdAt: string;
+            };
+        }>;
+    };
+    escrow_complete: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            escrowId: z.ZodString;
+            proofOfWork: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            escrowId: string;
+            proofOfWork: string;
+        }, {
+            escrowId: string;
+            proofOfWork: string;
+        }>;
+        handler: (input: EscrowCompleteInput) => Promise<{
+            success: boolean;
+            error: string;
+            message?: undefined;
+            escrow?: undefined;
+        } | {
+            success: boolean;
+            message: string;
+            escrow: {
+                id: string;
+                amount: number;
+                currency: import("../types/index.js").Currency;
+                status: import("../types/index.js").EscrowStatus;
+                completedAt: string | undefined;
+                proofOfWork: string | null;
+            };
+            error?: undefined;
+        }>;
+    };
+    escrow_status: {
+        description: string;
+        inputSchema: z.ZodObject<{
+            escrowId: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            escrowId: string;
+        }, {
+            escrowId: string;
+        }>;
+        handler: (input: EscrowStatusInput) => Promise<{
+            success: boolean;
+            error: string;
+            escrow?: undefined;
+        } | {
+            success: boolean;
+            escrow: {
+                id: string;
+                clientAgentId: string;
+                providerAgentId: string;
+                taskDescription: string;
+                amount: number;
+                currency: import("../types/index.js").Currency;
+                status: import("../types/index.js").EscrowStatus;
+                createdAt: string;
+                completedAt: string | null;
+                proofOfWork: string | null;
+            };
+            error?: undefined;
+        }>;
+    };
+};

package/dist/tools/escrow.js

@@ -0,0 +1,97 @@
+import { escrowCreateSchema, escrowCompleteSchema, escrowStatusSchema, } from '../schemas/index.js';
+import { createEscrow, getEscrow, completeEscrow } from '../services/firestore.js';
+export const escrowTools = {
+    escrow_create: {
+        description: 'Create a new escrow to lock funds for a task. The funds will be held until the task is completed.',
+        inputSchema: escrowCreateSchema,
+        handler: async (input) => {
+            const escrow = await createEscrow({
+                clientAgentId: input.clientAgentId,
+                providerAgentId: input.providerAgentId,
+                taskDescription: input.taskDescription,
+                amount: input.amount,
+                currency: input.currency,
+                status: 'pending',
+            });
+            return {
+                success: true,
+                escrowId: escrow.id,
+                message: `Escrow created successfully. ${input.amount} ${input.currency} locked for task: "${input.taskDescription}"`,
+                escrow: {
+                    id: escrow.id,
+                    amount: escrow.amount,
+                    currency: escrow.currency,
+                    status: escrow.status,
+                    providerAgentId: escrow.providerAgentId,
+                    createdAt: escrow.createdAt.toISOString(),
+                },
+            };
+        },
+    },
+    escrow_complete: {
+        description: 'Mark an escrow as complete and release the funds to the provider agent. Requires proof of work.',
+        inputSchema: escrowCompleteSchema,
+        handler: async (input) => {
+            const existingEscrow = await getEscrow(input.escrowId);
+            if (!existingEscrow) {
+                return {
+                    success: false,
+                    error: `Escrow not found: ${input.escrowId}`,
+                };
+            }
+            if (existingEscrow.status === 'completed') {
+                return {
+                    success: false,
+                    error: 'Escrow is already completed',
+                };
+            }
+            if (existingEscrow.status === 'cancelled') {
+                return {
+                    success: false,
+                    error: 'Escrow was cancelled',
+                };
+            }
+            const escrow = await completeEscrow(input.escrowId, input.proofOfWork);
+            return {
+                success: true,
+                message: `Escrow completed. ${escrow.amount} ${escrow.currency} released to ${escrow.providerAgentId}`,
+                escrow: {
+                    id: escrow.id,
+                    amount: escrow.amount,
+                    currency: escrow.currency,
+                    status: escrow.status,
+                    completedAt: escrow.completedAt?.toISOString(),
+                    proofOfWork: escrow.proofOfWork,
+                },
+            };
+        },
+    },
+    escrow_status: {
+        description: 'Check the current status of an escrow.',
+        inputSchema: escrowStatusSchema,
+        handler: async (input) => {
+            const escrow = await getEscrow(input.escrowId);
+            if (!escrow) {
+                return {
+                    success: false,
+                    error: `Escrow not found: ${input.escrowId}`,
+                };
+            }
+            return {
+                success: true,
+                escrow: {
+                    id: escrow.id,
+                    clientAgentId: escrow.clientAgentId,
+                    providerAgentId: escrow.providerAgentId,
+                    taskDescription: escrow.taskDescription,
+                    amount: escrow.amount,
+                    currency: escrow.currency,
+                    status: escrow.status,
+                    createdAt: escrow.createdAt.toISOString(),
+                    completedAt: escrow.completedAt?.toISOString() ?? null,
+                    proofOfWork: escrow.proofOfWork,
+                },
+            };
+        },
+    },
+};

package/dist/tools/index.d.ts

@@ -0,0 +1 @@
+export { escrowTools } from './escrow.js';

package/dist/tools/index.js

@@ -0,0 +1 @@
+export { escrowTools } from './escrow.js';

package/dist/types/index.d.ts

@@ -0,0 +1,43 @@
+export type EscrowStatus = 'pending' | 'in_progress' | 'completed' | 'disputed' | 'cancelled';
+export type Currency = 'USD' | 'USDC' | 'BTC';
+export type SubscriptionTier = 'free' | 'verified' | 'pro';
+export interface Escrow {
+    id: string;
+    clientAgentId: string;
+    providerAgentId: string;
+    taskDescription: string;
+    amount: number;
+    currency: Currency;
+    status: EscrowStatus;
+    createdAt: Date;
+    completedAt: Date | null;
+    proofOfWork: string | null;
+}
+export interface Agent {
+    id: string;
+    name: string;
+    description: string;
+    skills: string[];
+    createdAt: Date;
+    verified: boolean;
+    subscriptionTier: SubscriptionTier;
+    stats: AgentStats;
+}
+export interface AgentStats {
+    tasksCompleted: number;
+    totalEarned: number;
+    successRate: number;
+    avgCompletionTime: number;
+}
+export interface Task {
+    id: string;
+    escrowId: string;
+    description: string;
+    clientAgentId: string;
+    providerAgentId: string;
+    status: 'pending' | 'claimed' | 'in_progress' | 'completed' | 'failed';
+    createdAt: Date;
+    claimedAt: Date | null;
+    completedAt: Date | null;
+    result: string | null;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "clawdentials-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Clawdentials - escrow and reputation for AI agent commerce",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "clawdentials-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "tsx scripts/test-tools.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "ai-agents",
+    "escrow",
+    "reputation",
+    "claude",
+    "anthropic"
+  ],
+  "author": "Fernando Nikolic",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fernikolic/clawdentials.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://clawdentials.com",
+  "bugs": {
+    "url": "https://github.com/fernikolic/clawdentials/issues"
+  },
+  "dependencies": {
+    "@google-cloud/firestore": "8.2.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "firebase-admin": "^12.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "4.21.0",
+    "typescript": "^5.4.0"
+  }
+}