@artyfacts/mcp-server 1.0.0

package/src/index.ts

@@ -0,0 +1,25 @@
+/**
+ * @artyfacts/mcp-server
+ * 
+ * MCP (Model Context Protocol) server that exposes Artyfacts tools
+ * for use with Claude Code and other MCP-compatible clients.
+ * 
+ * @example
+ * ```typescript
+ * import { createMcpServer, startServer } from '@artyfacts/mcp-server';
+ * 
+ * const server = createMcpServer({
+ *   apiKey: 'your-api-key',
+ *   baseUrl: 'https://artyfacts.dev/api/v1',
+ * });
+ * 
+ * // Start as stdio server (for MCP)
+ * startServer(server);
+ * ```
+ */
+
+export { createMcpServer, ArtyfactsMcpServer } from './server';
+export type { McpServerConfig } from './server';
+
+// Re-export for convenience
+export { startServer } from './server';

package/src/server.ts

@@ -0,0 +1,605 @@
+/**
+ * Artyfacts MCP Server Implementation
+ * 
+ * Exposes Artyfacts tools via MCP (Model Context Protocol) for use
+ * with Claude Code and other MCP-compatible clients.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from '@modelcontextprotocol/sdk/types.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface McpServerConfig {
+  /** Artyfacts API key */
+  apiKey: string;
+  /** Artyfacts API base URL */
+  baseUrl?: string;
+  /** Server name */
+  name?: string;
+  /** Server version */
+  version?: string;
+}
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+const ARTYFACTS_TOOLS: Tool[] = [
+  // Organization tools
+  {
+    name: 'get_organization',
+    description: 'Get details about the current organization',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      required: [],
+    },
+  },
+  
+  // Project tools
+  {
+    name: 'list_projects',
+    description: 'List all projects in the organization',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', description: 'Max results (default 50)' },
+        offset: { type: 'number', description: 'Pagination offset' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_project',
+    description: 'Get details about a specific project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'Project ID' },
+      },
+      required: ['project_id'],
+    },
+  },
+  
+  // Artifact tools
+  {
+    name: 'list_artifacts',
+    description: 'List artifacts, optionally filtered by project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_id: { type: 'string', description: 'Filter by project' },
+        type: { type: 'string', description: 'Filter by type (goal, spec, research, etc.)' },
+        status: { type: 'string', description: 'Filter by status' },
+        limit: { type: 'number', description: 'Max results' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_artifact',
+    description: 'Get a specific artifact by ID',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+      },
+      required: ['artifact_id'],
+    },
+  },
+  {
+    name: 'create_artifact',
+    description: 'Create a new artifact',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Artifact title' },
+        type: { type: 'string', description: 'Type: goal, spec, research, report, experiment, decision' },
+        content: { type: 'string', description: 'Markdown content' },
+        project_id: { type: 'string', description: 'Project ID' },
+        parent_id: { type: 'string', description: 'Parent artifact ID' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Tags' },
+      },
+      required: ['title'],
+    },
+  },
+  {
+    name: 'update_artifact',
+    description: 'Update an existing artifact',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+        title: { type: 'string', description: 'New title' },
+        content: { type: 'string', description: 'New content' },
+        status: { type: 'string', description: 'New status' },
+      },
+      required: ['artifact_id'],
+    },
+  },
+  
+  // Section tools
+  {
+    name: 'list_sections',
+    description: 'List sections of an artifact',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+      },
+      required: ['artifact_id'],
+    },
+  },
+  {
+    name: 'get_section',
+    description: 'Get a specific section',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+        section_id: { type: 'string', description: 'Section ID' },
+      },
+      required: ['artifact_id', 'section_id'],
+    },
+  },
+  {
+    name: 'create_section',
+    description: 'Create a new section on an artifact',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+        section_id: { type: 'string', description: 'Section identifier (slug)' },
+        heading: { type: 'string', description: 'Section heading' },
+        content: { type: 'string', description: 'Markdown content' },
+        type: { type: 'string', description: 'Type: content, task, decision, blocker' },
+        position: { type: 'number', description: 'Order position' },
+      },
+      required: ['artifact_id', 'section_id', 'heading'],
+    },
+  },
+  {
+    name: 'update_section',
+    description: 'Update an existing section',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+        section_id: { type: 'string', description: 'Section ID' },
+        heading: { type: 'string', description: 'New heading' },
+        content: { type: 'string', description: 'New content' },
+        task_status: { type: 'string', description: 'Task status if type=task' },
+      },
+      required: ['artifact_id', 'section_id'],
+    },
+  },
+  {
+    name: 'delete_section',
+    description: 'Delete a section',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+        section_id: { type: 'string', description: 'Section ID' },
+      },
+      required: ['artifact_id', 'section_id'],
+    },
+  },
+  
+  // Task tools
+  {
+    name: 'list_tasks',
+    description: 'List tasks (sections with type=task)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Filter by artifact' },
+        status: { type: 'string', description: 'Filter by status: pending, in_progress, done, blocked' },
+        assignee: { type: 'string', description: 'Filter by assignee agent' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'claim_task',
+    description: 'Claim a task for the current agent',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID (section UUID)' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'complete_task',
+    description: 'Mark a task as complete',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID' },
+        output_url: { type: 'string', description: 'URL to deliverable (PR, doc, etc.)' },
+        summary: { type: 'string', description: 'Completion summary' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'block_task',
+    description: 'Mark a task as blocked',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID' },
+        reason: { type: 'string', description: 'Why it is blocked' },
+        blocker_type: { type: 'string', description: 'Type: decision, dependency, resource, external' },
+      },
+      required: ['task_id', 'reason'],
+    },
+  },
+  
+  // Agent tools
+  {
+    name: 'list_agents',
+    description: 'List all agents in the organization',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: { type: 'string', description: 'Filter by status: active, inactive' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'get_agent',
+    description: 'Get details about an agent',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agent_id: { type: 'string', description: 'Agent ID' },
+      },
+      required: ['agent_id'],
+    },
+  },
+  {
+    name: 'create_agent',
+    description: 'Register a new agent',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Agent display name' },
+        type: { type: 'string', description: 'Type: pm, engineering, qa, research, content, design' },
+        description: { type: 'string', description: 'What this agent does' },
+        capabilities: { type: 'array', items: { type: 'string' }, description: 'Agent capabilities' },
+        config: { type: 'object', description: 'Agent configuration' },
+      },
+      required: ['name', 'type'],
+    },
+  },
+  {
+    name: 'update_agent',
+    description: 'Update an agent',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agent_id: { type: 'string', description: 'Agent ID' },
+        name: { type: 'string', description: 'New name' },
+        status: { type: 'string', description: 'New status' },
+        config: { type: 'object', description: 'Updated config' },
+      },
+      required: ['agent_id'],
+    },
+  },
+  
+  // Blocker tools
+  {
+    name: 'list_blockers',
+    description: 'List blockers (decisions, dependencies needing resolution)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Filter by artifact' },
+        status: { type: 'string', description: 'Filter by status: open, resolved' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'create_blocker',
+    description: 'Create a blocker (decision request, dependency, etc.)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        artifact_id: { type: 'string', description: 'Artifact ID' },
+        kind: { type: 'string', description: 'Kind: decision, dependency, resource, external' },
+        title: { type: 'string', description: 'Blocker title' },
+        description: { type: 'string', description: 'Details' },
+        options: { type: 'array', description: 'Options for decisions' },
+        blocked_tasks: { type: 'array', items: { type: 'string' }, description: 'Task IDs blocked by this' },
+      },
+      required: ['artifact_id', 'kind', 'title'],
+    },
+  },
+  {
+    name: 'resolve_blocker',
+    description: 'Resolve a blocker',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        blocker_id: { type: 'string', description: 'Blocker ID' },
+        resolution: { type: 'string', description: 'How it was resolved' },
+        selected_option: { type: 'string', description: 'Selected option (for decisions)' },
+      },
+      required: ['blocker_id', 'resolution'],
+    },
+  },
+  
+  // Search tools
+  {
+    name: 'search_artifacts',
+    description: 'Search artifacts by text query',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        type: { type: 'string', description: 'Filter by type' },
+        limit: { type: 'number', description: 'Max results' },
+      },
+      required: ['query'],
+    },
+  },
+  
+  // Context tools
+  {
+    name: 'get_task_context',
+    description: 'Get full context for a task (org, project, artifact, related sections)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task ID' },
+      },
+      required: ['task_id'],
+    },
+  },
+];
+
+// ============================================================================
+// API Client
+// ============================================================================
+
+class ArtyfactsApiClient {
+  constructor(
+    private baseUrl: string,
+    private apiKey: string
+  ) {}
+
+  async request(method: string, path: string, body?: unknown): Promise<unknown> {
+    const url = `${this.baseUrl}${path}`;
+    
+    const response = await fetch(url, {
+      method,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: 'Request failed' })) as { error?: string };
+      throw new Error(error.error || `HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    return response.json();
+  }
+
+  get(path: string) { return this.request('GET', path); }
+  post(path: string, body?: unknown) { return this.request('POST', path, body); }
+  patch(path: string, body?: unknown) { return this.request('PATCH', path, body); }
+  delete(path: string) { return this.request('DELETE', path); }
+}
+
+// ============================================================================
+// Tool Handlers
+// ============================================================================
+
+type ToolHandler = (client: ArtyfactsApiClient, args: Record<string, unknown>) => Promise<unknown>;
+
+const toolHandlers: Record<string, ToolHandler> = {
+  // Organization
+  get_organization: (client) => client.get('/org'),
+  
+  // Projects
+  list_projects: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.limit) params.set('limit', String(args.limit));
+    if (args.offset) params.set('offset', String(args.offset));
+    return client.get(`/projects?${params}`);
+  },
+  get_project: (client, args) => client.get(`/projects/${args.project_id}`),
+  
+  // Artifacts
+  list_artifacts: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.project_id) params.set('project_id', String(args.project_id));
+    if (args.type) params.set('type', String(args.type));
+    if (args.status) params.set('status', String(args.status));
+    if (args.limit) params.set('limit', String(args.limit));
+    return client.get(`/artifacts?${params}`);
+  },
+  get_artifact: (client, args) => client.get(`/artifacts/${args.artifact_id}`),
+  create_artifact: (client, args) => client.post('/artifacts', args),
+  update_artifact: (client, args) => {
+    const { artifact_id, ...body } = args;
+    return client.patch(`/artifacts/${artifact_id}`, body);
+  },
+  
+  // Sections
+  list_sections: (client, args) => client.get(`/artifacts/${args.artifact_id}/sections`),
+  get_section: (client, args) => client.get(`/artifacts/${args.artifact_id}/sections/${args.section_id}`),
+  create_section: (client, args) => {
+    const { artifact_id, ...body } = args;
+    return client.post(`/artifacts/${artifact_id}/sections`, body);
+  },
+  update_section: (client, args) => {
+    const { artifact_id, section_id, ...body } = args;
+    return client.patch(`/artifacts/${artifact_id}/sections/${section_id}`, body);
+  },
+  delete_section: (client, args) => client.delete(`/artifacts/${args.artifact_id}/sections/${args.section_id}`),
+  
+  // Tasks
+  list_tasks: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.artifact_id) params.set('artifact_id', String(args.artifact_id));
+    if (args.status) params.set('status', String(args.status));
+    if (args.assignee) params.set('assignee', String(args.assignee));
+    return client.get(`/tasks?${params}`);
+  },
+  claim_task: (client, args) => client.post(`/tasks/${args.task_id}/claim`),
+  complete_task: (client, args) => {
+    const { task_id, ...body } = args;
+    return client.post(`/tasks/${task_id}/complete`, body);
+  },
+  block_task: (client, args) => {
+    const { task_id, ...body } = args;
+    return client.post(`/tasks/${task_id}/block`, body);
+  },
+  
+  // Agents
+  list_agents: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.status) params.set('status', String(args.status));
+    return client.get(`/agents?${params}`);
+  },
+  get_agent: (client, args) => client.get(`/agents/${args.agent_id}`),
+  create_agent: (client, args) => client.post('/agents', args),
+  update_agent: (client, args) => {
+    const { agent_id, ...body } = args;
+    return client.patch(`/agents/${agent_id}`, body);
+  },
+  
+  // Blockers
+  list_blockers: (client, args) => {
+    const params = new URLSearchParams();
+    if (args.artifact_id) params.set('artifact_id', String(args.artifact_id));
+    if (args.status) params.set('status', String(args.status));
+    return client.get(`/blockers?${params}`);
+  },
+  create_blocker: (client, args) => {
+    const { artifact_id, ...body } = args;
+    return client.post(`/artifacts/${artifact_id}/blockers`, body);
+  },
+  resolve_blocker: (client, args) => {
+    const { blocker_id, ...body } = args;
+    return client.post(`/blockers/${blocker_id}/resolve`, body);
+  },
+  
+  // Search
+  search_artifacts: (client, args) => {
+    const params = new URLSearchParams();
+    params.set('q', String(args.query));
+    if (args.type) params.set('type', String(args.type));
+    if (args.limit) params.set('limit', String(args.limit));
+    return client.get(`/search?${params}`);
+  },
+  
+  // Context
+  get_task_context: (client, args) => client.get(`/tasks/${args.task_id}/context`),
+};
+
+// ============================================================================
+// MCP Server Class
+// ============================================================================
+
+export class ArtyfactsMcpServer {
+  private server: Server;
+  private client: ArtyfactsApiClient;
+  private config: McpServerConfig;
+
+  constructor(config: McpServerConfig) {
+    this.config = config;
+    this.client = new ArtyfactsApiClient(
+      config.baseUrl || 'https://artyfacts.dev/api/v1',
+      config.apiKey
+    );
+
+    this.server = new Server(
+      {
+        name: config.name || 'artyfacts-mcp',
+        version: config.version || '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return { tools: ARTYFACTS_TOOLS };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      
+      const handler = toolHandlers[name];
+      if (!handler) {
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+      }
+
+      try {
+        const result = await handler(this.client, args || {});
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: 'text', text: `Error: ${message}` }],
+          isError: true,
+        };
+      }
+    });
+  }
+
+  async start(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    
+    // Log to stderr so it doesn't interfere with MCP protocol on stdout
+    console.error(`Artyfacts MCP server running (${ARTYFACTS_TOOLS.length} tools)`);
+  }
+
+  getServer(): Server {
+    return this.server;
+  }
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+export function createMcpServer(config: McpServerConfig): ArtyfactsMcpServer {
+  return new ArtyfactsMcpServer(config);
+}
+
+export async function startServer(server: ArtyfactsMcpServer): Promise<void> {
+  await server.start();
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}