@svadmin/mcp 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@svadmin/mcp",
+  "version": "0.1.0",
+  "description": "MCP (Model Context Protocol) server — expose svadmin DataProvider as tools for AI agents",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src/**/*"
+  ],
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@svadmin/core": "^0.5.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": "zuohuadong",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zuohuadong/svadmin.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/zuohuadong/svadmin#readme",
+  "bugs": {
+    "url": "https://github.com/zuohuadong/svadmin/issues"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,250 @@
+import { describe, test, expect } from 'bun:test';
+import { createMCPServer } from './index';
+import type { MCPRequest } from './index';
+
+// ─── Mock DataProvider ───────────────────────────────────────
+
+interface MockFilter { field: string; operator: string; value: unknown }
+interface MockPagination { current?: number; pageSize?: number }
+
+const mockData: Record<string, Record<string, unknown>[]> = {
+  posts: [
+    { id: '1', title: 'Hello World', status: 'published' },
+    { id: '2', title: 'Draft Post', status: 'draft' },
+    { id: '3', title: 'Another Post', status: 'published' },
+  ],
+  users: [
+    { id: '1', name: 'Alice', email: 'alice@test.com' },
+    { id: '2', name: 'Bob', email: 'bob@test.com' },
+  ],
+};
+
+const mockDataProvider = {
+  getList: async (params: { resource: string; pagination?: MockPagination; filters?: MockFilter[] }) => {
+    let data = [...(mockData[params.resource] ?? [])];
+    if (params.filters && Array.isArray(params.filters)) {
+      for (const f of params.filters) {
+        data = data.filter(item => item[f.field] === f.value);
+      }
+    }
+    const page = params.pagination?.current ?? 1;
+    const size = params.pagination?.pageSize ?? 10;
+    const start = (page - 1) * size;
+    return { data: data.slice(start, start + size), total: data.length };
+  },
+  getOne: async (params: { resource: string; id: string | number }) => {
+    const item = (mockData[params.resource] ?? []).find(r => r.id === params.id);
+    if (!item) throw new Error(`Not found: ${params.resource}/${params.id}`);
+    return { data: item };
+  },
+  getMany: async (params: { resource: string; ids: (string | number)[] }) => {
+    const items = (mockData[params.resource] ?? []).filter(r => params.ids.includes(r.id as string));
+    return { data: items };
+  },
+  create: async (params: { resource: string; variables: unknown }) => {
+    const newItem = { id: String(Date.now()), ...(params.variables as Record<string, unknown>) };
+    return { data: newItem };
+  },
+  update: async (params: { resource: string; id: string | number; variables: unknown }) => {
+    const existing = (mockData[params.resource] ?? []).find(r => r.id === params.id);
+    const updated = { ...existing, ...(params.variables as Record<string, unknown>) };
+    return { data: updated };
+  },
+  deleteOne: async (params: { resource: string; id: string | number }) => {
+    const item = (mockData[params.resource] ?? []).find(r => r.id === params.id);
+    return { data: item ?? { id: params.id } };
+  },
+  getApiUrl: () => 'http://localhost:3000/api',
+};
+
+// ─── Helper ──────────────────────────────────────────────────
+
+function makeRequest(method: string, params?: Record<string, unknown>): MCPRequest {
+  return { jsonrpc: '2.0', id: 1, method, params };
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+
+describe('createMCPServer', () => {
+  const server = createMCPServer({
+    dataProvider: mockDataProvider as Parameters<typeof createMCPServer>[0]['dataProvider'],
+    resources: ['posts', 'users'],
+  });
+
+  test('generates correct number of tools (read + write)', () => {
+    const tools = server.getTools();
+    // getList, getOne, getMany, create, update, delete = 6
+    expect(tools).toHaveLength(6);
+    expect(tools.map(t => t.name)).toEqual([
+      'svadmin_getList', 'svadmin_getOne', 'svadmin_getMany',
+      'svadmin_create', 'svadmin_update', 'svadmin_delete',
+    ]);
+  });
+
+  test('readOnly mode excludes write tools', () => {
+    const readOnlyServer = createMCPServer({
+      dataProvider: mockDataProvider as Parameters<typeof createMCPServer>[0]['dataProvider'],
+      resources: ['posts'],
+      readOnly: true,
+    });
+    const tools = readOnlyServer.getTools();
+    expect(tools).toHaveLength(3);
+    expect(tools.map(t => t.name)).toEqual([
+      'svadmin_getList', 'svadmin_getOne', 'svadmin_getMany',
+    ]);
+  });
+
+  test('tool resource enum matches configured resources', () => {
+    const tools = server.getTools();
+    const getListTool = tools.find(t => t.name === 'svadmin_getList')!;
+    expect(getListTool.inputSchema.properties.resource.enum).toEqual(['posts', 'users']);
+  });
+
+  test('getServerInfo returns correct metadata', () => {
+    const info = server.getServerInfo();
+    expect(info.name).toBe('@svadmin/mcp');
+    expect(info.version).toBe('0.1.0');
+    expect(info.tools).toHaveLength(6);
+  });
+});
+
+describe('MCP JSON-RPC handling', () => {
+  const server = createMCPServer({
+    dataProvider: mockDataProvider as Parameters<typeof createMCPServer>[0]['dataProvider'],
+    resources: ['posts', 'users'],
+  });
+
+  test('initialize handshake', async () => {
+    const res = await server.handleRequest(makeRequest('initialize'));
+    expect(res.error).toBeUndefined();
+    const result = res.result as Record<string, unknown>;
+    expect(result.protocolVersion).toBe('2024-11-05');
+    expect((result.serverInfo as Record<string, unknown>).name).toBe('@svadmin/mcp');
+  });
+
+  test('tools/list returns all tools', async () => {
+    const res = await server.handleRequest(makeRequest('tools/list'));
+    expect(res.error).toBeUndefined();
+    const result = res.result as { tools: unknown[] };
+    expect(result.tools).toHaveLength(6);
+  });
+
+  test('tools/call getList returns paginated data', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_getList',
+      arguments: { resource: 'posts', page: 1, pageSize: 2 },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data).toHaveLength(2);
+    expect(parsed.total).toBe(3);
+  });
+
+  test('tools/call getList with filters', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_getList',
+      arguments: {
+        resource: 'posts',
+        filters: JSON.stringify([{ field: 'status', operator: 'eq', value: 'draft' }]),
+      },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data).toHaveLength(1);
+    expect(parsed.data[0].title).toBe('Draft Post');
+  });
+
+  test('tools/call getOne returns single record', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_getOne',
+      arguments: { resource: 'users', id: '1' },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data.name).toBe('Alice');
+  });
+
+  test('tools/call getMany returns multiple records', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_getMany',
+      arguments: { resource: 'users', ids: '1,2' },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data).toHaveLength(2);
+  });
+
+  test('tools/call create returns new record', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_create',
+      arguments: {
+        resource: 'posts',
+        data: JSON.stringify({ title: 'New Post', status: 'draft' }),
+      },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data.title).toBe('New Post');
+    expect(parsed.data.id).toBeDefined();
+  });
+
+  test('tools/call update returns modified record', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_update',
+      arguments: {
+        resource: 'posts',
+        id: '1',
+        data: JSON.stringify({ title: 'Updated Title' }),
+      },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data.title).toBe('Updated Title');
+  });
+
+  test('tools/call delete returns deleted record', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_delete',
+      arguments: { resource: 'posts', id: '2' },
+    }));
+
+    expect(res.error).toBeUndefined();
+    const result = res.result as { content: { type: string; text: string }[] };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.data.id).toBe('2');
+  });
+
+  test('unknown tool returns error', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {
+      name: 'svadmin_nope',
+      arguments: {},
+    }));
+
+    expect(res.error).toBeDefined();
+    expect(res.error!.code).toBe(-32602);
+  });
+
+  test('unknown method returns error', async () => {
+    const res = await server.handleRequest(makeRequest('whatever'));
+    expect(res.error).toBeDefined();
+    expect(res.error!.code).toBe(-32601);
+  });
+
+  test('missing tool name returns error', async () => {
+    const res = await server.handleRequest(makeRequest('tools/call', {}));
+    expect(res.error).toBeDefined();
+    expect(res.error!.code).toBe(-32602);
+  });
+});

package/src/index.ts

@@ -0,0 +1,376 @@
+/**
+ * @svadmin/mcp — Model Context Protocol server for svadmin DataProvider
+ *
+ * Exposes svadmin's DataProvider CRUD operations as MCP-compatible tools,
+ * allowing any MCP client (Claude Desktop, Cursor, custom agents) to
+ * query and mutate admin data through a standardized protocol.
+ *
+ * @example
+ * ```ts
+ * import { createMCPServer } from '@svadmin/mcp';
+ * import { myDataProvider } from './data-provider';
+ *
+ * const server = createMCPServer({
+ *   dataProvider: myDataProvider,
+ *   resources: ['posts', 'users', 'orders'],
+ * });
+ *
+ * // Start stdio transport (for Claude Desktop / Cursor)
+ * server.listen();
+ *
+ * // Or get the handler for HTTP transport
+ * const handler = server.createHandler();
+ * ```
+ */
+
+import type { DataProvider, ResourceDefinition } from '@svadmin/core';
+
+// ─── Types ───────────────────────────────────────────────────
+
+export interface MCPServerOptions {
+  /** The svadmin DataProvider to expose via MCP */
+  dataProvider: DataProvider;
+  /** List of resource names to expose (whitelist) */
+  resources: string[];
+  /** Optional resource definitions for richer tool descriptions */
+  resourceDefinitions?: ResourceDefinition[];
+  /** Server name shown to MCP clients */
+  name?: string;
+  /** Server version */
+  version?: string;
+  /** When true, only expose read operations (getList, getOne, getMany) */
+  readOnly?: boolean;
+}
+
+/** MCP Tool definition following the Model Context Protocol spec */
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, MCPPropertySchema>;
+    required?: string[];
+  };
+}
+
+export interface MCPPropertySchema {
+  type: string;
+  description?: string;
+  enum?: string[];
+  items?: MCPPropertySchema;
+  default?: unknown;
+}
+
+/** MCP JSON-RPC request */
+export interface MCPRequest {
+  jsonrpc: '2.0';
+  id: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+/** MCP JSON-RPC response */
+export interface MCPResponse {
+  jsonrpc: '2.0';
+  id: string | number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+/** MCP Server instance */
+export interface MCPServer {
+  /** Get all tool definitions */
+  getTools(): MCPTool[];
+  /** Handle a single MCP JSON-RPC request */
+  handleRequest(request: MCPRequest): Promise<MCPResponse>;
+  /** Get the server info for MCP handshake */
+  getServerInfo(): { name: string; version: string; tools: MCPTool[] };
+}
+
+// ─── Tool Generation ─────────────────────────────────────────
+
+function buildResourceParam(resources: string[]): MCPPropertySchema {
+  return {
+    type: 'string',
+    description: 'Resource name to operate on',
+    enum: resources,
+  };
+}
+
+function generateTools(options: MCPServerOptions): MCPTool[] {
+  const { resources, readOnly = false } = options;
+  const tools: MCPTool[] = [];
+
+  // getList
+  tools.push({
+    name: 'svadmin_getList',
+    description: 'Fetch a paginated list of records from a resource. Supports filtering and sorting.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resource: buildResourceParam(resources),
+        page: { type: 'number', description: 'Page number (1-indexed)', default: 1 },
+        pageSize: { type: 'number', description: 'Number of records per page', default: 10 },
+        sortField: { type: 'string', description: 'Field to sort by' },
+        sortOrder: { type: 'string', description: 'Sort direction', enum: ['asc', 'desc'] },
+        filters: { type: 'string', description: 'JSON-encoded filter array: [{"field":"status","operator":"eq","value":"active"}]' },
+      },
+      required: ['resource'],
+    },
+  });
+
+  // getOne
+  tools.push({
+    name: 'svadmin_getOne',
+    description: 'Fetch a single record by ID from a resource.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resource: buildResourceParam(resources),
+        id: { type: 'string', description: 'Record ID' },
+      },
+      required: ['resource', 'id'],
+    },
+  });
+
+  // getMany
+  tools.push({
+    name: 'svadmin_getMany',
+    description: 'Fetch multiple records by their IDs from a resource.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resource: buildResourceParam(resources),
+        ids: { type: 'string', description: 'Comma-separated list of record IDs' },
+      },
+      required: ['resource', 'ids'],
+    },
+  });
+
+  if (!readOnly) {
+    // create
+    tools.push({
+      name: 'svadmin_create',
+      description: 'Create a new record in a resource.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          resource: buildResourceParam(resources),
+          data: { type: 'string', description: 'JSON-encoded record data to create' },
+        },
+        required: ['resource', 'data'],
+      },
+    });
+
+    // update
+    tools.push({
+      name: 'svadmin_update',
+      description: 'Update an existing record by ID in a resource.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          resource: buildResourceParam(resources),
+          id: { type: 'string', description: 'Record ID to update' },
+          data: { type: 'string', description: 'JSON-encoded partial record data' },
+        },
+        required: ['resource', 'id', 'data'],
+      },
+    });
+
+    // delete
+    tools.push({
+      name: 'svadmin_delete',
+      description: 'Delete a record by ID from a resource.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          resource: buildResourceParam(resources),
+          id: { type: 'string', description: 'Record ID to delete' },
+        },
+        required: ['resource', 'id'],
+      },
+    });
+  }
+
+  return tools;
+}
+
+// ─── Request Handler ─────────────────────────────────────────
+
+async function handleToolCall(
+  toolName: string,
+  args: Record<string, unknown>,
+  dp: DataProvider,
+): Promise<unknown> {
+  switch (toolName) {
+    case 'svadmin_getList': {
+      const resource = args.resource as string;
+      const page = (args.page as number) ?? 1;
+      const pageSize = (args.pageSize as number) ?? 10;
+      const sorters = args.sortField
+        ? [{ field: args.sortField as string, order: (args.sortOrder as 'asc' | 'desc') ?? 'asc' }]
+        : undefined;
+      const filters = args.filters
+        ? JSON.parse(args.filters as string)
+        : undefined;
+
+      return dp.getList({
+        resource,
+        pagination: { current: page, pageSize },
+        sorters,
+        filters,
+      });
+    }
+
+    case 'svadmin_getOne': {
+      return dp.getOne({
+        resource: args.resource as string,
+        id: args.id as string,
+      });
+    }
+
+    case 'svadmin_getMany': {
+      const ids = (args.ids as string).split(',').map(id => id.trim());
+      if (dp.getMany) {
+        return dp.getMany({ resource: args.resource as string, ids });
+      }
+      // Fallback: fetch one by one
+      const results = await Promise.all(
+        ids.map(id => dp.getOne({ resource: args.resource as string, id }))
+      );
+      return { data: results.map(r => r.data) };
+    }
+
+    case 'svadmin_create': {
+      const data = JSON.parse(args.data as string);
+      return dp.create({
+        resource: args.resource as string,
+        variables: data,
+      });
+    }
+
+    case 'svadmin_update': {
+      const data = JSON.parse(args.data as string);
+      return dp.update({
+        resource: args.resource as string,
+        id: args.id as string,
+        variables: data,
+      });
+    }
+
+    case 'svadmin_delete': {
+      return dp.deleteOne({
+        resource: args.resource as string,
+        id: args.id as string,
+      });
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${toolName}`);
+  }
+}
+
+// ─── Server Factory ──────────────────────────────────────────
+
+/**
+ * Create an MCP server that exposes svadmin DataProvider operations as tools.
+ *
+ * @example
+ * ```ts
+ * const server = createMCPServer({
+ *   dataProvider: myDataProvider,
+ *   resources: ['posts', 'users'],
+ *   readOnly: false,
+ * });
+ *
+ * // Handle a JSON-RPC request
+ * const response = await server.handleRequest({
+ *   jsonrpc: '2.0',
+ *   id: 1,
+ *   method: 'tools/call',
+ *   params: { name: 'svadmin_getList', arguments: { resource: 'posts', page: 1 } },
+ * });
+ * ```
+ */
+export function createMCPServer(options: MCPServerOptions): MCPServer {
+  const serverName = options.name ?? '@svadmin/mcp';
+  const serverVersion = options.version ?? '0.1.0';
+  const tools = generateTools(options);
+
+  async function handleRequest(request: MCPRequest): Promise<MCPResponse> {
+    const { id, method, params } = request;
+
+    try {
+      switch (method) {
+        case 'initialize':
+          return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+              protocolVersion: '2024-11-05',
+              serverInfo: { name: serverName, version: serverVersion },
+              capabilities: { tools: {} },
+            },
+          };
+
+        case 'tools/list':
+          return {
+            jsonrpc: '2.0',
+            id,
+            result: { tools },
+          };
+
+        case 'tools/call': {
+          const toolName = (params as Record<string, unknown>)?.name as string;
+          const toolArgs = ((params as Record<string, unknown>)?.arguments ?? {}) as Record<string, unknown>;
+
+          if (!toolName) {
+            return {
+              jsonrpc: '2.0',
+              id,
+              error: { code: -32602, message: 'Missing tool name' },
+            };
+          }
+
+          const knownTool = tools.find(t => t.name === toolName);
+          if (!knownTool) {
+            return {
+              jsonrpc: '2.0',
+              id,
+              error: { code: -32602, message: `Unknown tool: ${toolName}` },
+            };
+          }
+
+          const result = await handleToolCall(toolName, toolArgs, options.dataProvider);
+          return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            },
+          };
+        }
+
+        default:
+          return {
+            jsonrpc: '2.0',
+            id,
+            error: { code: -32601, message: `Method not found: ${method}` },
+          };
+      }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32000, message },
+      };
+    }
+  }
+
+  return {
+    getTools: () => tools,
+    getServerInfo: () => ({ name: serverName, version: serverVersion, tools }),
+    handleRequest,
+  };
+}