gyrus 0.1.0

package/src/server/mcp-stdio.ts

@@ -0,0 +1,526 @@
+/**
+ * MCP Server configuration and setup
+ * Creates the MCP server instance with stdio transport
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { WorkspaceManager } from "../services/workspace.ts";
+import {
+  gyrusListTool,
+  gyrusListSchema,
+  executeGyrusList,
+  gyrusSwitchTool,
+  gyrusSwitchSchema,
+  executeGyrusSwitch,
+  knowledgeListTool,
+  knowledgeListSchema,
+  executeKnowledgeList,
+  knowledgeReadTool,
+  knowledgeReadSchema,
+  executeKnowledgeRead,
+  knowledgeSearchTool,
+  knowledgeSearchSchema,
+  executeKnowledgeSearch,
+  knowledgeCreateTool,
+  knowledgeCreateSchema,
+  executeKnowledgeCreate,
+  knowledgeUpdateTool,
+  knowledgeUpdateSchema,
+  executeKnowledgeUpdate,
+  adrListTool,
+  adrListSchema,
+  executeAdrList,
+  adrReadTool,
+  adrReadSchema,
+  executeAdrRead,
+  adrSearchTool,
+  adrSearchSchema,
+  executeAdrSearch,
+  adrCreateTool,
+  adrCreateSchema,
+  executeAdrCreate,
+  adrUpdateTool,
+  adrUpdateSchema,
+  executeAdrUpdate,
+} from "../tools/index.ts";
+
+/**
+ * Create and configure the MCP server
+ */
+export function createServer(manager: WorkspaceManager): McpServer {
+  const server = new McpServer({
+    name: "gyrus",
+    version: "0.1.0",
+  });
+
+  // =============================================================================
+  // Gyrus Workspace Tools
+  // =============================================================================
+
+  // Register gyrus_list tool
+  server.tool(gyrusListTool.name, gyrusListTool.description, {}, async () => {
+    const result = await executeGyrusList(manager, {});
+    return {
+      content: [{ type: "text", text: result }],
+    };
+  });
+
+  // Register gyrus_switch tool
+  server.tool(
+    gyrusSwitchTool.name,
+    gyrusSwitchTool.description,
+    {
+      name: z.string().describe("The name of the workspace to switch to"),
+    },
+    async (args) => {
+      const input = gyrusSwitchSchema.parse(args);
+      const result = await executeGyrusSwitch(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // =============================================================================
+  // Knowledge Tools
+  // =============================================================================
+
+  // Register knowledge_list tool
+  server.tool(
+    knowledgeListTool.name,
+    knowledgeListTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      category: z
+        .enum(["projects", "patterns", "tools", "gotchas", "decisions"])
+        .optional()
+        .describe("Filter by category folder"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter by tags (matches notes with any of these tags)"),
+    },
+    async (args) => {
+      const input = knowledgeListSchema.parse(args);
+      const result = await executeKnowledgeList(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register knowledge_read tool
+  server.tool(
+    knowledgeReadTool.name,
+    knowledgeReadTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      id: z
+        .string()
+        .optional()
+        .describe("The unique ID of the note to read (from frontmatter)"),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "The relative path of the note (e.g., 'patterns/pattern-retry-with-backoff.md')",
+        ),
+    },
+    async (args) => {
+      const input = knowledgeReadSchema.parse(args);
+      const result = await executeKnowledgeRead(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register knowledge_search tool
+  server.tool(
+    knowledgeSearchTool.name,
+    knowledgeSearchTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      query: z
+        .string()
+        .optional()
+        .describe(
+          "Text to search for in note titles, content, and descriptions",
+        ),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter by tags (matches notes with any of these tags)"),
+      category: z
+        .enum(["projects", "patterns", "tools", "gotchas", "decisions"])
+        .optional()
+        .describe("Filter by category folder"),
+    },
+    async (args) => {
+      const input = knowledgeSearchSchema.parse(args);
+      const result = await executeKnowledgeSearch(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register knowledge_create tool
+  server.tool(
+    knowledgeCreateTool.name,
+    knowledgeCreateTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      id: z
+        .string()
+        .describe(
+          "Unique identifier for the note in kebab-case (e.g., 'pattern-retry-with-backoff')",
+        ),
+      title: z.string().describe("Human-readable title for the note"),
+      category: z
+        .enum(["projects", "patterns", "tools", "gotchas", "decisions"])
+        .describe("Category folder to place the note in"),
+      content: z
+        .string()
+        .describe("Markdown content for the note (without frontmatter)"),
+      tags: z.array(z.string()).optional().describe("Tags for categorization"),
+      related: z
+        .array(z.string())
+        .optional()
+        .describe("IDs of related notes for cross-referencing"),
+      description: z
+        .string()
+        .optional()
+        .describe("Brief description of the note"),
+    },
+    async (args) => {
+      const input = knowledgeCreateSchema.parse(args);
+      const result = await executeKnowledgeCreate(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register knowledge_update tool
+  server.tool(
+    knowledgeUpdateTool.name,
+    knowledgeUpdateTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      id: z.string().describe("The unique ID of the note to update"),
+      title: z
+        .string()
+        .optional()
+        .describe("New title for the note (optional)"),
+      content: z
+        .string()
+        .optional()
+        .describe(
+          "New markdown content for the note (optional, replaces existing content)",
+        ),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("New tags for the note (optional, replaces existing tags)"),
+      related: z
+        .array(z.string())
+        .optional()
+        .describe("New related note IDs (optional, replaces existing related)"),
+      description: z
+        .string()
+        .optional()
+        .describe("New description for the note (optional)"),
+    },
+    async (args) => {
+      const input = knowledgeUpdateSchema.parse(args);
+      const result = await executeKnowledgeUpdate(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // =============================================================================
+  // ADR Tools
+  // =============================================================================
+
+  // Register adr_list tool
+  server.tool(
+    adrListTool.name,
+    adrListTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      status: z
+        .enum([
+          "todo",
+          "in-progress",
+          "in-review",
+          "blocked",
+          "completed",
+          "deprecated",
+        ])
+        .optional()
+        .describe("Filter by ADR status"),
+      type: z
+        .enum(["enhancement", "debug", "research"])
+        .optional()
+        .describe("Filter by ADR type"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter by tags (matches ADRs with any of these tags)"),
+    },
+    async (args) => {
+      const input = adrListSchema.parse(args);
+      const result = await executeAdrList(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register adr_read tool
+  server.tool(
+    adrReadTool.name,
+    adrReadTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      name: z
+        .string()
+        .describe(
+          "The ADR name (filename without .md) or partial match to find",
+        ),
+    },
+    async (args) => {
+      const input = adrReadSchema.parse(args);
+      const result = await executeAdrRead(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register adr_search tool
+  server.tool(
+    adrSearchTool.name,
+    adrSearchTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      query: z
+        .string()
+        .optional()
+        .describe(
+          "Text to search for in ADR titles, descriptions, names, and content",
+        ),
+      status: z
+        .enum([
+          "todo",
+          "in-progress",
+          "in-review",
+          "blocked",
+          "completed",
+          "deprecated",
+        ])
+        .optional()
+        .describe("Filter by ADR status"),
+      type: z
+        .enum(["enhancement", "debug", "research"])
+        .optional()
+        .describe("Filter by ADR type"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("Filter by tags (matches ADRs with any of these tags)"),
+    },
+    async (args) => {
+      const input = adrSearchSchema.parse(args);
+      const result = await executeAdrSearch(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register adr_create tool
+  server.tool(
+    adrCreateTool.name,
+    adrCreateTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      title: z
+        .string()
+        .describe(
+          "Human-readable title for the ADR (e.g., 'Cloud Deployment Feature')",
+        ),
+      type: z
+        .enum(["enhancement", "debug", "research"])
+        .describe(
+          "ADR type: enhancement (new feature), debug (bug fix), or research (exploration)",
+        ),
+      workingFolder: z
+        .string()
+        .describe(
+          "Full path to the project working folder (e.g., '/Users/name/project')",
+        ),
+      description: z
+        .string()
+        .optional()
+        .describe("Brief one-line description of what this ADR covers"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Tags for categorization (e.g., ['frontend', 'api', 'performance'])",
+        ),
+      status: z
+        .enum([
+          "todo",
+          "in-progress",
+          "in-review",
+          "blocked",
+          "completed",
+          "deprecated",
+        ])
+        .optional()
+        .describe("Initial status (defaults to 'todo')"),
+      content: z
+        .string()
+        .optional()
+        .describe(
+          "Optional custom content (without frontmatter). If not provided, uses default template.",
+        ),
+    },
+    async (args) => {
+      const input = adrCreateSchema.parse(args);
+      const result = await executeAdrCreate(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  // Register adr_update tool
+  server.tool(
+    adrUpdateTool.name,
+    adrUpdateTool.description,
+    {
+      workspace: z
+        .string()
+        .optional()
+        .describe(
+          "Target workspace name. If not provided, uses the active workspace.",
+        ),
+      name: z
+        .string()
+        .describe(
+          "The ADR name (filename without .md) or partial match to find",
+        ),
+      title: z.string().optional().describe("New title for the ADR (optional)"),
+      description: z
+        .string()
+        .optional()
+        .describe("New description for the ADR (optional)"),
+      status: z
+        .enum([
+          "todo",
+          "in-progress",
+          "in-review",
+          "blocked",
+          "completed",
+          "deprecated",
+        ])
+        .optional()
+        .describe("New status for the ADR (optional)"),
+      type: z
+        .enum(["enhancement", "debug", "research"])
+        .optional()
+        .describe("New type for the ADR (optional)"),
+      tags: z
+        .array(z.string())
+        .optional()
+        .describe("New tags for the ADR (optional, replaces existing tags)"),
+      content: z
+        .string()
+        .optional()
+        .describe(
+          "New markdown content for the ADR (optional, replaces existing content)",
+        ),
+      workingFolder: z
+        .string()
+        .optional()
+        .describe("New working folder path (optional)"),
+    },
+    async (args) => {
+      const input = adrUpdateSchema.parse(args);
+      const result = await executeAdrUpdate(manager, input);
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    },
+  );
+
+  return server;
+}
+
+/**
+ * Create and start the server with stdio transport
+ */
+export async function startStdioServer(
+  manager: WorkspaceManager,
+): Promise<void> {
+  const server = createServer(manager);
+  const transport = new StdioServerTransport();
+
+  await server.connect(transport);
+
+  // Log to stderr (not stdout, as stdout is used for MCP protocol)
+  console.error("  Server connected via stdio");
+}