catpaw-observer-mcp 1.0.0

package/README.md

@@ -0,0 +1,68 @@
+# CatPaw Observer MCP
+
+CatPaw 全链路观测平台 MCP Server —— 为 AI Agent（Claude Desktop、Cursor、Cline 等）提供任务与执行链路的记录、查询和统计能力。
+
+## 功能
+
+通过 MCP 协议暴露以下工具：
+
+| 工具 | 说明 |
+| --- | --- |
+| `create_task` | 创建观测任务 |
+| `record_trace` | 记录一次执行的完整链路（耗时、Token、成本、步骤等） |
+| `list_tasks` | 查询任务列表 |
+| `get_task_detail` | 获取任务详情与执行记录汇总 |
+| `get_trace_detail` | 获取单条链路详情 |
+| `get_statistics` | 全局统计汇总（成功率、平均耗时、总 Token、总成本） |
+| `delete_task` | 删除任务及其所有记录 |
+
+数据保存在本机 `~/.catpaw-observer` 目录下的 JSON 文件中。
+
+## 安装
+
+```bash
+npm install -g catpaw-observer-mcp
+```
+
+## 使用
+
+### 命令行
+
+```bash
+catpaw-observer-mcp
+```
+
+### Claude Desktop
+
+在 `claude_desktop_config.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "catpaw-observer": {
+      "command": "catpaw-observer-mcp"
+    }
+  }
+}
+```
+
+### 使用 npx
+
+```json
+{
+  "mcpServers": {
+    "catpaw-observer": {
+      "command": "npx",
+      "args": ["-y", "catpaw-observer-mcp"]
+    }
+  }
+}
+```
+
+## 环境要求
+
+- Node.js >= 18
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,62 @@
+#!/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 { getTasks, getTask, saveTask, deleteTask, getTraces, getTracesByTask, saveTrace } from './store.js';
+const server = new McpServer({ name: 'catpaw-observer-mcp', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.registerTool('create_task', {
+    description: '创建一个新的 CatPaw 观测任务',
+    inputSchema: { name: z.string().describe('任务名称'), category: z.string().optional().describe('任务分类'), description: z.string().optional().describe('任务描述'), prompt: z.string().describe('Prompt 内容') },
+}, async ({ name, category, description, prompt }) => {
+    const task = await saveTask({ name, category: category || '其他', description: description || '', prompt, status: 'pending' });
+    return { content: [{ type: 'text', text: JSON.stringify({ message: '观测任务创建成功', task }, null, 2) }] };
+});
+server.registerTool('record_trace', {
+    description: '记录 CatPaw 执行全链路数据',
+    inputSchema: { taskId: z.string().describe('任务ID'), status: z.enum(['success', 'failed', 'running']).describe('状态'), totalDuration: z.number().describe('总耗时(ms)'), inputTokens: z.number().describe('输入Token'), outputTokens: z.number().describe('输出Token'), model: z.string().optional().describe('模型'), cost: z.number().optional().describe('成本'), qualityScore: z.number().optional().describe('质量评分'), steps: z.array(z.object({ name: z.string(), duration: z.number(), inputTokens: z.number(), outputTokens: z.number(), status: z.enum(['success', 'running', 'warning', 'failed']) })).describe('步骤') },
+}, async ({ taskId, status, totalDuration, inputTokens, outputTokens, model, cost, qualityScore, steps }) => {
+    const trace = await saveTrace({ taskId, status, totalDuration, totalTokens: inputTokens + outputTokens, inputTokens, outputTokens, model: model || 'CatPaw', cost: cost || 0, qualityScore: qualityScore || null, stepCount: steps.length, steps: steps.map(s => ({ name: s.name, duration: s.duration, inputTokens: s.inputTokens, outputTokens: s.outputTokens, status: s.status })) });
+    const task = await getTask(taskId);
+    if (task)
+        await saveTask({ ...task, status: status === 'success' ? 'completed' : status });
+    return { content: [{ type: 'text', text: JSON.stringify({ message: '链路记录保存成功', trace: { id: trace.id, totalDuration: `${(trace.totalDuration / 1000).toFixed(2)}s`, totalTokens: trace.totalTokens.toLocaleString(), cost: `$${trace.cost}` } }, null, 2) }] };
+});
+server.registerTool('list_tasks', {
+    description: '查询任务列表', inputSchema: { status: z.enum(['pending', 'running', 'completed', 'failed']).optional(), limit: z.number().optional() },
+}, async ({ status, limit }) => {
+    let tasks = await getTasks();
+    if (status)
+        tasks = tasks.filter(t => t.status === status);
+    tasks = tasks.slice(-(limit || 20)).reverse();
+    return { content: [{ type: 'text', text: JSON.stringify({ total: tasks.length, tasks: tasks.map(t => ({ id: t.id, name: t.name, category: t.category, status: t.status })) }, null, 2) }] };
+});
+server.registerTool('get_task_detail', {
+    description: '获取任务详情和执行记录', inputSchema: { taskId: z.string().describe('任务ID') },
+}, async ({ taskId }) => {
+    const task = await getTask(taskId);
+    if (!task)
+        return { content: [{ type: 'text', text: JSON.stringify({ error: '任务不存在' }) }], isError: true };
+    const traces = await getTracesByTask(taskId);
+    return { content: [{ type: 'text', text: JSON.stringify({ task, traces, summary: { totalExecutions: traces.length, totalTokens: traces.reduce((s, t) => s + t.totalTokens, 0).toLocaleString(), totalCost: `$${traces.reduce((s, t) => s + t.cost, 0).toFixed(3)}` } }, null, 2) }] };
+});
+server.registerTool('get_trace_detail', {
+    description: '获取链路详情', inputSchema: { traceId: z.string().describe('链路ID') },
+}, async ({ traceId }) => {
+    const trace = (await getTraces()).find(t => t.id === traceId);
+    if (!trace)
+        return { content: [{ type: 'text', text: JSON.stringify({ error: '链路记录不存在' }) }], isError: true };
+    return { content: [{ type: 'text', text: JSON.stringify({ trace, steps: trace.steps.map((s, i) => ({ step: i + 1, name: s.name, duration: `${(s.duration / 1000).toFixed(2)}s`, tokens: (s.inputTokens + s.outputTokens).toLocaleString(), status: s.status })) }, null, 2) }] };
+});
+server.registerTool('get_statistics', {
+    description: '获取全局统计汇总', inputSchema: {},
+}, async () => {
+    const tasks = await getTasks();
+    const traces = await getTraces();
+    const ok = traces.filter(t => t.status === 'success');
+    return { content: [{ type: 'text', text: JSON.stringify({ statistics: { totalTasks: tasks.length, totalTraces: traces.length, successRate: traces.length ? `${Math.round(ok.length / traces.length * 100)}%` : 'N/A', avgDuration: ok.length ? `${Math.round(ok.reduce((s, t) => s + t.totalDuration, 0) / ok.length / 1000)}s` : 'N/A', totalTokens: traces.reduce((s, t) => s + t.totalTokens, 0).toLocaleString(), totalCost: `$${traces.reduce((s, t) => s + t.cost, 0).toFixed(3)}` } }, null, 2) }] };
+});
+server.registerTool('delete_task', {
+    description: '删除任务及所有记录', inputSchema: { taskId: z.string().describe('任务ID') },
+}, async ({ taskId }) => { await deleteTask(taskId); return { content: [{ type: 'text', text: JSON.stringify({ message: '任务已删除', taskId }) }] }; });
+async function main() { await server.connect(new StdioServerTransport()); console.error('CatPaw Observer MCP Server 已启动'); }
+main().catch(console.error);

package/dist/store.d.ts

@@ -0,0 +1,44 @@
+export interface TraceStep {
+    name: string;
+    duration: number;
+    inputTokens: number;
+    outputTokens: number;
+    status: 'success' | 'running' | 'warning' | 'failed';
+}
+export interface Trace {
+    id: string;
+    taskId: string;
+    status: 'success' | 'failed' | 'running';
+    totalDuration: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    model: string;
+    cost: number;
+    qualityScore: number | null;
+    stepCount: number;
+    steps: TraceStep[];
+    createdAt: string;
+}
+export interface Task {
+    id: string;
+    name: string;
+    description: string;
+    category: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    createdAt: string;
+}
+export declare function getTasks(): Promise<Task[]>;
+export declare function getTask(id: string): Promise<Task | undefined>;
+export declare function saveTask(t: Omit<Task, 'id' | 'createdAt'> & {
+    id?: string;
+    createdAt?: string;
+}): Promise<Task>;
+export declare function deleteTask(id: string): Promise<void>;
+export declare function getTraces(): Promise<Trace[]>;
+export declare function getTracesByTask(id: string): Promise<Trace[]>;
+export declare function saveTrace(t: Omit<Trace, 'id' | 'createdAt'> & {
+    id?: string;
+    createdAt?: string;
+}): Promise<Trace>;

package/dist/store.js

@@ -0,0 +1,57 @@
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+const DATA_DIR = join(homedir(), '.catpaw-observer');
+const TASKS_FILE = join(DATA_DIR, 'tasks.json');
+const TRACES_FILE = join(DATA_DIR, 'traces.json');
+async function ensureDir() {
+    try {
+        await access(DATA_DIR);
+    }
+    catch {
+        await mkdir(DATA_DIR, { recursive: true });
+    }
+}
+async function readJson(p, d) {
+    try {
+        return JSON.parse(await readFile(p, 'utf-8'));
+    }
+    catch {
+        return d;
+    }
+}
+async function writeJson(p, d) {
+    await ensureDir();
+    await writeFile(p, JSON.stringify(d, null, 2), 'utf-8');
+}
+function genId(p) { return `${p}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`; }
+export async function getTasks() { return readJson(TASKS_FILE, []); }
+export async function getTask(id) { return (await getTasks()).find(t => t.id === id); }
+export async function saveTask(t) {
+    const all = await getTasks();
+    const n = { ...t, id: t.id || genId('task'), createdAt: t.createdAt || new Date().toISOString() };
+    const i = all.findIndex(x => x.id === n.id);
+    if (i >= 0)
+        all[i] = n;
+    else
+        all.push(n);
+    await writeJson(TASKS_FILE, all);
+    return n;
+}
+export async function deleteTask(id) {
+    await writeJson(TASKS_FILE, (await getTasks()).filter(t => t.id !== id));
+    await writeJson(TRACES_FILE, (await getTraces()).filter(t => t.taskId !== id));
+}
+export async function getTraces() { return readJson(TRACES_FILE, []); }
+export async function getTracesByTask(id) { return (await getTraces()).filter(t => t.taskId === id); }
+export async function saveTrace(t) {
+    const all = await getTraces();
+    const n = { ...t, id: t.id || genId('trace'), createdAt: t.createdAt || new Date().toISOString() };
+    const i = all.findIndex(x => x.id === n.id);
+    if (i >= 0)
+        all[i] = n;
+    else
+        all.push(n);
+    await writeJson(TRACES_FILE, all);
+    return n;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "catpaw-observer-mcp",
+  "version": "1.0.0",
+  "description": "CatPaw 全链路观测平台 MCP Server",
+  "type": "module",
+  "bin": {
+    "catpaw-observer-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}