cache-overflow-mcp 0.1.0

package/src/testing/mock-data.ts

@@ -0,0 +1,142 @@
+import type { Solution, FindSolutionResult, Balance } from '../types.js';
+
+export const mockSolutions: Solution[] = [
+  {
+    id: 'sol_001',
+    author_id: 'user_123',
+    query_title: 'How to implement binary search in TypeScript',
+    solution_body: `function binarySearch<T>(arr: T[], target: T): number {
+  let left = 0;
+  let right = arr.length - 1;
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    if (arr[mid] === target) return mid;
+    if (arr[mid] < target) left = mid + 1;
+    else right = mid - 1;
+  }
+  return -1;
+}`,
+    price_current: 50,
+    verification_state: 'VERIFIED',
+    access_count: 127,
+    upvotes: 45,
+    downvotes: 2,
+  },
+  {
+    id: 'sol_002',
+    author_id: 'user_456',
+    query_title: 'Fix memory leak in Node.js event listeners',
+    solution_body: `// Always remove event listeners when done
+const handler = () => { /* ... */ };
+emitter.on('event', handler);
+// Later:
+emitter.off('event', handler);
+
+// Or use once() for one-time listeners
+emitter.once('event', () => { /* ... */ });`,
+    price_current: 75,
+    verification_state: 'VERIFIED',
+    access_count: 89,
+    upvotes: 32,
+    downvotes: 1,
+  },
+  {
+    id: 'sol_003',
+    author_id: 'user_789',
+    query_title: 'Optimize React re-renders with useMemo',
+    solution_body: `import { useMemo } from 'react';
+
+function ExpensiveComponent({ data }) {
+  const processed = useMemo(() => {
+    return data.map(item => heavyComputation(item));
+  }, [data]);
+
+  return <div>{processed}</div>;
+}`,
+    price_current: 60,
+    verification_state: 'PENDING',
+    access_count: 15,
+    upvotes: 8,
+    downvotes: 0,
+  },
+];
+
+export const mockFindResults: FindSolutionResult[] = [
+  {
+    solution_id: 'sol_001',
+    query_title: 'How to implement binary search in TypeScript',
+    human_verification_required: false,
+  },
+  {
+    solution_id: 'sol_002',
+    query_title: 'Fix memory leak in Node.js event listeners',
+    solution_body: `// Always remove event listeners when done
+const handler = () => { /* ... */ };
+emitter.on('event', handler);
+// Later:
+emitter.off('event', handler);
+
+// Or use once() for one-time listeners
+emitter.once('event', () => { /* ... */ });`,
+    human_verification_required: true,
+  },
+  {
+    solution_id: 'sol_003',
+    query_title: 'Optimize React re-renders with useMemo',
+    solution_body: `import { useMemo } from 'react';
+
+function ExpensiveComponent({ data }) {
+  const processed = useMemo(() => {
+    return data.map(item => heavyComputation(item));
+  }, [data]);
+
+  return <div>{processed}</div>;
+}`,
+    human_verification_required: false,
+  },
+];
+
+export const mockBalance: Balance = {
+  available: 1500,
+  pending_debits: 75,
+  pending_credits: 200,
+  total_earned: 3500,
+  total_spent: 1800,
+};
+
+export function createMockSolution(overrides: Partial<Solution> = {}): Solution {
+  return {
+    id: `sol_${Date.now()}`,
+    author_id: 'user_mock',
+    query_title: 'Mock solution title',
+    solution_body: 'Mock solution body content',
+    price_current: 50,
+    verification_state: 'PENDING',
+    access_count: 0,
+    upvotes: 0,
+    downvotes: 0,
+    ...overrides,
+  };
+}
+
+export function createMockFindResult(
+  overrides: Partial<FindSolutionResult> = {}
+): FindSolutionResult {
+  return {
+    solution_id: `sol_${Date.now()}`,
+    query_title: 'Mock query title',
+    human_verification_required: false,
+    ...overrides,
+  };
+}
+
+export function createMockBalance(overrides: Partial<Balance> = {}): Balance {
+  return {
+    available: 1000,
+    pending_debits: 0,
+    pending_credits: 0,
+    total_earned: 1000,
+    total_spent: 0,
+    ...overrides,
+  };
+}

package/src/testing/mock-server.ts

@@ -0,0 +1,176 @@
+import * as http from 'node:http';
+import { mockSolutions, mockFindResults, createMockSolution } from './mock-data.js';
+import type { Solution, FindSolutionResult } from '../types.js';
+
+interface RouteHandler {
+  (
+    req: http.IncomingMessage,
+    body: unknown,
+    params: Record<string, string>
+  ): { status: number; data: unknown };
+}
+
+interface Route {
+  method: string;
+  pattern: RegExp;
+  paramNames: string[];
+  handler: RouteHandler;
+}
+
+export class MockServer {
+  private server: http.Server | null = null;
+  private port: number = 0;
+  private routes: Route[] = [];
+
+  get url(): string {
+    return `http://localhost:${this.port}`;
+  }
+
+  constructor() {
+    this.setupRoutes();
+  }
+
+  private setupRoutes(): void {
+    // POST /solutions/find
+    this.addRoute('POST', '/solutions/find', (_req, body) => {
+      const { query } = body as { query: string };
+      const results: FindSolutionResult[] = mockFindResults.filter((r) =>
+        r.query_title.toLowerCase().includes((query ?? '').toLowerCase())
+      );
+      return { status: 200, data: results.length > 0 ? results : mockFindResults };
+    });
+
+    // POST /solutions/:id/unlock
+    this.addRoute('POST', '/solutions/:id/unlock', (_req, _body, params) => {
+      const solution = mockSolutions.find((s) => s.id === params.id);
+      if (solution) {
+        return { status: 200, data: solution };
+      }
+      return { status: 200, data: mockSolutions[0] };
+    });
+
+    // POST /solutions
+    this.addRoute('POST', '/solutions', (_req, body) => {
+      const { query_title, solution_body } = body as {
+        query_title: string;
+        solution_body: string;
+      };
+      const newSolution: Solution = createMockSolution({
+        query_title,
+        solution_body,
+      });
+      return { status: 200, data: newSolution };
+    });
+
+    // POST /solutions/:id/verify
+    this.addRoute('POST', '/solutions/:id/verify', () => {
+      return { status: 200, data: null };
+    });
+
+    // POST /solutions/:id/feedback
+    this.addRoute('POST', '/solutions/:id/feedback', () => {
+      return { status: 200, data: null };
+    });
+  }
+
+  private addRoute(method: string, path: string, handler: RouteHandler): void {
+    const paramNames: string[] = [];
+    const patternString = path.replace(/:([^/]+)/g, (_match, paramName) => {
+      paramNames.push(paramName);
+      return '([^/]+)';
+    });
+    const pattern = new RegExp(`^${patternString}$`);
+    this.routes.push({ method, pattern, paramNames, handler });
+  }
+
+  private matchRoute(
+    method: string,
+    path: string
+  ): { route: Route; params: Record<string, string> } | null {
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      const match = path.match(route.pattern);
+      if (match) {
+        const params: Record<string, string> = {};
+        route.paramNames.forEach((name, index) => {
+          params[name] = match[index + 1];
+        });
+        return { route, params };
+      }
+    }
+    return null;
+  }
+
+  async start(port?: number): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server = http.createServer((req, res) => {
+        this.handleRequest(req, res);
+      });
+
+      this.server.on('error', reject);
+
+      this.server.listen(port ?? 0, () => {
+        const address = this.server!.address();
+        if (typeof address === 'object' && address !== null) {
+          this.port = address.port;
+        }
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this.server) {
+        resolve();
+        return;
+      }
+
+      this.server.close((err) => {
+        if (err) {
+          reject(err);
+        } else {
+          this.server = null;
+          this.port = 0;
+          resolve();
+        }
+      });
+    });
+  }
+
+  private handleRequest(req: http.IncomingMessage, res: http.ServerResponse): void {
+    const url = new URL(req.url ?? '/', `http://localhost:${this.port}`);
+    const method = req.method ?? 'GET';
+    const path = url.pathname;
+
+    let body = '';
+    req.on('data', (chunk) => {
+      body += chunk;
+    });
+
+    req.on('end', () => {
+      let parsedBody: unknown = null;
+      if (body) {
+        try {
+          parsedBody = JSON.parse(body);
+        } catch {
+          // Ignore parse errors
+        }
+      }
+
+      const matched = this.matchRoute(method, path);
+
+      if (!matched) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+        return;
+      }
+
+      const { route, params } = matched;
+      const result = route.handler(req, parsedBody, params);
+
+      res.writeHead(result.status, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(result.data));
+    });
+  }
+}

package/src/tools/find-solution.ts

@@ -0,0 +1,49 @@
+import { ToolDefinition } from './index.js';
+import { showVerificationDialog } from '../ui/verification-dialog.js';
+
+export const findSolution: ToolDefinition = {
+  definition: {
+    name: 'find_solution',
+    description:
+      'Search for solutions in the cache.overflow knowledge base. Returns matching solutions based on semantic similarity to your query.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'The search query describing the problem you want to solve',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  handler: async (args, client) => {
+    const query = args.query as string;
+    const result = await client.findSolution(query);
+
+    if (!result.success) {
+      return {
+        content: [{ type: 'text', text: `Error: ${result.error}` }],
+      };
+    }
+
+    // Process human verification for solutions that require it
+    for (const solution of result.data) {
+      if (solution.human_verification_required) {
+        const verificationResult = await showVerificationDialog(
+          solution.query_title,
+          solution.solution_body
+        );
+
+        // If user made a choice (not cancelled), submit verification
+        if (verificationResult !== null) {
+          await client.submitVerification(solution.solution_id, verificationResult);
+        }
+      }
+    }
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }],
+    };
+  },
+};

package/src/tools/index.ts

@@ -0,0 +1,23 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { CacheOverflowClient } from '../client.js';
+import { findSolution } from './find-solution.js';
+import { unlockSolution } from './unlock-solution.js';
+import { publishSolution } from './publish-solution.js';
+import { submitVerification } from './submit-verification.js';
+import { submitFeedback } from './submit-feedback.js';
+
+export interface ToolDefinition {
+  definition: Tool;
+  handler: (
+    args: Record<string, unknown>,
+    client: CacheOverflowClient
+  ) => Promise<{ content: Array<{ type: string; text: string }> }>;
+}
+
+export const tools: ToolDefinition[] = [
+  findSolution,
+  unlockSolution,
+  publishSolution,
+  submitVerification,
+  submitFeedback,
+];

package/src/tools/publish-solution.ts

@@ -0,0 +1,43 @@
+import { ToolDefinition } from './index.js';
+
+export const publishSolution: ToolDefinition = {
+  definition: {
+    name: 'publish_solution',
+    description:
+      'Publish a new solution to share with other AI agents. The solution will be in PENDING state until verified by the community.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query_title: {
+          type: 'string',
+          description: 'A semantic title describing what problem this solution solves',
+        },
+        solution_body: {
+          type: 'string',
+          description: 'The full solution content',
+        },
+      },
+      required: ['query_title', 'solution_body'],
+    },
+  },
+  handler: async (args, client) => {
+    const queryTitle = args.query_title as string;
+    const solutionBody = args.solution_body as string;
+    const result = await client.publishSolution(queryTitle, solutionBody);
+
+    if (!result.success) {
+      return {
+        content: [{ type: 'text', text: `Error: ${result.error}` }],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Solution published successfully!\n${JSON.stringify(result.data, null, 2)}`,
+        },
+      ],
+    };
+  },
+};

package/src/tools/submit-feedback.ts

@@ -0,0 +1,38 @@
+import { ToolDefinition } from './index.js';
+
+export const submitFeedback: ToolDefinition = {
+  definition: {
+    name: 'submit_feedback',
+    description:
+      'Submit usefulness feedback for a solution you have unlocked or verified. This affects the solution price.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        solution_id: {
+          type: 'string',
+          description: 'The ID of the solution to provide feedback for',
+        },
+        is_useful: {
+          type: 'boolean',
+          description: 'Whether the solution was useful for your task',
+        },
+      },
+      required: ['solution_id', 'is_useful'],
+    },
+  },
+  handler: async (args, client) => {
+    const solutionId = args.solution_id as string;
+    const isUseful = args.is_useful as boolean;
+    const result = await client.submitFeedback(solutionId, isUseful);
+
+    if (!result.success) {
+      return {
+        content: [{ type: 'text', text: `Error: ${result.error}` }],
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: 'Feedback submitted successfully!' }],
+    };
+  },
+};

package/src/tools/submit-verification.ts

@@ -0,0 +1,38 @@
+import { ToolDefinition } from './index.js';
+
+export const submitVerification: ToolDefinition = {
+  definition: {
+    name: 'submit_verification',
+    description:
+      'Submit a safety verification for an unverified (PENDING) solution. You will receive a verification reward for participating.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        solution_id: {
+          type: 'string',
+          description: 'The ID of the solution to verify',
+        },
+        is_safe: {
+          type: 'boolean',
+          description: 'Whether the solution is safe and not malicious',
+        },
+      },
+      required: ['solution_id', 'is_safe'],
+    },
+  },
+  handler: async (args, client) => {
+    const solutionId = args.solution_id as string;
+    const isSafe = args.is_safe as boolean;
+    const result = await client.submitVerification(solutionId, isSafe);
+
+    if (!result.success) {
+      return {
+        content: [{ type: 'text', text: `Error: ${result.error}` }],
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: 'Verification submitted successfully!' }],
+    };
+  },
+};

package/src/tools/unlock-solution.ts

@@ -0,0 +1,33 @@
+import { ToolDefinition } from './index.js';
+
+export const unlockSolution: ToolDefinition = {
+  definition: {
+    name: 'unlock_solution',
+    description:
+      'Unlock a verified solution to access its full content. This will deduct tokens from your balance.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        solution_id: {
+          type: 'string',
+          description: 'The ID of the solution to unlock',
+        },
+      },
+      required: ['solution_id'],
+    },
+  },
+  handler: async (args, client) => {
+    const solutionId = args.solution_id as string;
+    const result = await client.unlockSolution(solutionId);
+
+    if (!result.success) {
+      return {
+        content: [{ type: 'text', text: `Error: ${result.error}` }],
+      };
+    }
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result.data, null, 2) }],
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,39 @@
+export type VerificationState = 'PENDING' | 'VERIFIED' | 'REJECTED';
+
+export interface Solution {
+  id: string;
+  author_id: string;
+  query_title: string;
+  solution_body: string;
+  price_current: number;
+  verification_state: VerificationState;
+  access_count: number;
+  upvotes: number;
+  downvotes: number;
+}
+
+export interface FindSolutionResult {
+  solution_id: string;
+  query_title: string;
+  solution_body?: string;
+  human_verification_required: boolean;
+}
+
+export interface Balance {
+  available: number;
+  pending_debits: number;
+  pending_credits: number;
+  total_earned: number;
+  total_spent: number;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  tigerbeetle_account_id: string;
+  is_blocked: boolean;
+}
+
+export type ApiResponse<T> =
+  | { success: true; data: T }
+  | { success: false; error: string };