@duckwalk/mcp-server 0.1.2

package/dist/server.js

@@ -0,0 +1,239 @@
+import {
+  createGuidedSession,
+  createPrReviewSession,
+  getDuckWalkContract,
+  getGuidedSession,
+  pathfinder,
+  updateStepStatus,
+  validateGuidedSessionInput
+} from "./chunk-IIW4JPFI.js";
+
+// src/server.ts
+import path from "path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+var rootDir = process.env.DUCKWALK_ROOT ?? process.cwd();
+var server = new Server(
+  {
+    name: "duckwalk-mcp",
+    version: "0.1.2"
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+function textResult(payload) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ]
+  };
+}
+function getArguments(input) {
+  if (!input || typeof input !== "object") {
+    return {};
+  }
+  return input;
+}
+function resolveTargetRoot(args) {
+  const workspaceRoot = args.workspaceRoot;
+  if (typeof workspaceRoot === "string" && workspaceRoot.trim().length > 0) {
+    return path.resolve(workspaceRoot);
+  }
+  return rootDir;
+}
+function resolveExpectedMode(value) {
+  return value === "implementation" || value === "pr_review" || value === "codebase_walkthrough" ? value : void 0;
+}
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "get_duckwalk_contract",
+      description: "Return the duckWalk session contract, rules, and example payloads for Codex.",
+      inputSchema: {
+        type: "object",
+        properties: {}
+      }
+    },
+    {
+      name: "validate_guided_session",
+      description: "Validate a GuidedSession payload without writing files, and return a normalized summary.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          session: {
+            type: "object",
+            description: "A full GuidedSession payload."
+          },
+          expectMode: {
+            type: "string",
+            enum: ["implementation", "pr_review", "codebase_walkthrough"],
+            description: "Optional expected mode check for the session."
+          }
+        },
+        required: ["session"]
+      }
+    },
+    {
+      name: "create_guided_session",
+      description: "Validate and persist an implementation guided session.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Optional absolute workspace root where .guided-implementation files should be written."
+          },
+          session: {
+            type: "object",
+            description: "A full GuidedSession payload."
+          }
+        },
+        required: ["session"]
+      }
+    },
+    {
+      name: "create_pr_review_session",
+      description: "Validate and persist a PR review guided session.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Optional absolute workspace root where .guided-implementation files should be written."
+          },
+          session: {
+            type: "object",
+            description: "A full GuidedSession payload with mode pr_review."
+          }
+        },
+        required: ["session"]
+      }
+    },
+    {
+      name: "pathfinder",
+      description: "Validate and persist a question-driven codebase walkthrough session.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Optional absolute workspace root where .guided-implementation files should be written."
+          },
+          session: {
+            type: "object",
+            description: "A full GuidedSession payload with mode codebase_walkthrough."
+          }
+        },
+        required: ["session"]
+      }
+    },
+    {
+      name: "get_guided_session",
+      description: "Read the current session or a specific session by ID.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Optional absolute workspace root where the guided session should be read."
+          },
+          sessionId: {
+            type: "string"
+          }
+        }
+      }
+    },
+    {
+      name: "update_step_status",
+      description: "Update one step status in the current guided session state.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Optional absolute workspace root where the guided session state should be updated."
+          },
+          sessionId: {
+            type: "string"
+          },
+          stepId: {
+            type: "string"
+          },
+          status: {
+            type: "string",
+            enum: ["pending", "active", "complete", "skipped"]
+          }
+        },
+        required: ["sessionId", "stepId", "status"]
+      }
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const args = getArguments(request.params.arguments);
+  const targetRoot = resolveTargetRoot(args);
+  switch (request.params.name) {
+    case "get_duckwalk_contract":
+      return textResult(getDuckWalkContract());
+    case "validate_guided_session": {
+      const expectMode = resolveExpectedMode(args.expectMode);
+      const payload = {
+        session: args.session,
+        ...expectMode ? { expectMode } : {}
+      };
+      return textResult(validateGuidedSessionInput(payload));
+    }
+    case "create_guided_session":
+      return textResult(
+        await createGuidedSession(
+          targetRoot,
+          args.session
+        )
+      );
+    case "create_pr_review_session":
+      return textResult(
+        await createPrReviewSession(
+          targetRoot,
+          args.session
+        )
+      );
+    case "pathfinder":
+      return textResult(
+        await pathfinder(targetRoot, args.session)
+      );
+    case "get_guided_session":
+      return textResult(
+        await getGuidedSession(
+          targetRoot,
+          typeof args.sessionId === "string" ? args.sessionId : void 0
+        )
+      );
+    case "update_step_status":
+      return textResult(
+        await updateStepStatus(targetRoot, {
+          sessionId: String(args.sessionId),
+          stepId: String(args.stepId),
+          status: args.status
+        })
+      );
+    default:
+      throw new Error(`Unknown tool: ${request.params.name}`);
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  console.error("[duckwalk-mcp] fatal error");
+  console.error(error);
+  process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["import path from \"node:path\";\n\nimport { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { CallToolRequestSchema, ListToolsRequestSchema } from \"@modelcontextprotocol/sdk/types.js\";\n\nimport {\n  createGuidedSession,\n  createPrReviewSession,\n  getDuckWalkContract,\n  getGuidedSession,\n  pathfinder,\n  updateStepStatus,\n  validateGuidedSessionInput\n} from \"./service\";\n\nconst rootDir = process.env.DUCKWALK_ROOT ?? process.cwd();\n\nconst server = new Server(\n  {\n    name: \"duckwalk-mcp\",\n    version: \"0.1.2\"\n  },\n  {\n    capabilities: {\n      tools: {}\n    }\n  }\n);\n\nfunction textResult(payload: unknown) {\n  return {\n    content: [\n      {\n        type: \"text\" as const,\n        text: JSON.stringify(payload, null, 2)\n      }\n    ]\n  };\n}\n\nfunction getArguments(input: unknown): Record<string, unknown> {\n  if (!input || typeof input !== \"object\") {\n    return {};\n  }\n  return input as Record<string, unknown>;\n}\n\nfunction resolveTargetRoot(args: Record<string, unknown>): string {\n  const workspaceRoot = args.workspaceRoot;\n  if (typeof workspaceRoot === \"string\" && workspaceRoot.trim().length > 0) {\n    return path.resolve(workspaceRoot);\n  }\n\n  return rootDir;\n}\n\nfunction resolveExpectedMode(\n  value: unknown\n): Parameters<typeof validateGuidedSessionInput>[0][\"expectMode\"] {\n  return value === \"implementation\" ||\n    value === \"pr_review\" ||\n    value === \"codebase_walkthrough\"\n    ? value\n    : undefined;\n}\n\nserver.setRequestHandler(ListToolsRequestSchema, async () => ({\n  tools: [\n    {\n      name: \"get_duckwalk_contract\",\n      description:\n        \"Return the duckWalk session contract, rules, and example payloads for Codex.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {}\n      }\n    },\n    {\n      name: \"validate_guided_session\",\n      description:\n        \"Validate a GuidedSession payload without writing files, and return a normalized summary.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          session: {\n            type: \"object\",\n            description: \"A full GuidedSession payload.\"\n          },\n          expectMode: {\n            type: \"string\",\n            enum: [\"implementation\", \"pr_review\", \"codebase_walkthrough\"],\n            description: \"Optional expected mode check for the session.\"\n          }\n        },\n        required: [\"session\"]\n      }\n    },\n    {\n      name: \"create_guided_session\",\n      description: \"Validate and persist an implementation guided session.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          workspaceRoot: {\n            type: \"string\",\n            description:\n              \"Optional absolute workspace root where .guided-implementation files should be written.\"\n          },\n          session: {\n            type: \"object\",\n            description: \"A full GuidedSession payload.\"\n          }\n        },\n        required: [\"session\"]\n      }\n    },\n    {\n      name: \"create_pr_review_session\",\n      description: \"Validate and persist a PR review guided session.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          workspaceRoot: {\n            type: \"string\",\n            description:\n              \"Optional absolute workspace root where .guided-implementation files should be written.\"\n          },\n          session: {\n            type: \"object\",\n            description: \"A full GuidedSession payload with mode pr_review.\"\n          }\n        },\n        required: [\"session\"]\n      }\n    },\n    {\n      name: \"pathfinder\",\n      description: \"Validate and persist a question-driven codebase walkthrough session.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          workspaceRoot: {\n            type: \"string\",\n            description:\n              \"Optional absolute workspace root where .guided-implementation files should be written.\"\n          },\n          session: {\n            type: \"object\",\n            description: \"A full GuidedSession payload with mode codebase_walkthrough.\"\n          }\n        },\n        required: [\"session\"]\n      }\n    },\n    {\n      name: \"get_guided_session\",\n      description: \"Read the current session or a specific session by ID.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          workspaceRoot: {\n            type: \"string\",\n            description:\n              \"Optional absolute workspace root where the guided session should be read.\"\n          },\n          sessionId: {\n            type: \"string\"\n          }\n        }\n      }\n    },\n    {\n      name: \"update_step_status\",\n      description: \"Update one step status in the current guided session state.\",\n      inputSchema: {\n        type: \"object\",\n        properties: {\n          workspaceRoot: {\n            type: \"string\",\n            description:\n              \"Optional absolute workspace root where the guided session state should be updated.\"\n          },\n          sessionId: {\n            type: \"string\"\n          },\n          stepId: {\n            type: \"string\"\n          },\n          status: {\n            type: \"string\",\n            enum: [\"pending\", \"active\", \"complete\", \"skipped\"]\n          }\n        },\n        required: [\"sessionId\", \"stepId\", \"status\"]\n      }\n    }\n  ]\n}));\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n  const args = getArguments(request.params.arguments);\n  const targetRoot = resolveTargetRoot(args);\n\n  switch (request.params.name) {\n    case \"get_duckwalk_contract\":\n      return textResult(getDuckWalkContract());\n    case \"validate_guided_session\":\n      {\n        const expectMode = resolveExpectedMode(args.expectMode);\n        const payload = {\n          session: args.session as Parameters<typeof validateGuidedSessionInput>[0][\"session\"],\n          ...(expectMode ? { expectMode } : {})\n        };\n\n        return textResult(validateGuidedSessionInput(payload));\n      }\n    case \"create_guided_session\":\n      return textResult(\n        await createGuidedSession(\n          targetRoot,\n          args.session as Parameters<typeof createGuidedSession>[1]\n        )\n      );\n    case \"create_pr_review_session\":\n      return textResult(\n        await createPrReviewSession(\n          targetRoot,\n          args.session as Parameters<typeof createPrReviewSession>[1]\n        )\n      );\n    case \"pathfinder\":\n      return textResult(\n        await pathfinder(targetRoot, args.session as Parameters<typeof pathfinder>[1])\n      );\n    case \"get_guided_session\":\n      return textResult(\n        await getGuidedSession(\n          targetRoot,\n          typeof args.sessionId === \"string\" ? args.sessionId : undefined\n        )\n      );\n    case \"update_step_status\":\n      return textResult(\n        await updateStepStatus(targetRoot, {\n          sessionId: String(args.sessionId),\n          stepId: String(args.stepId),\n          status: args.status as Parameters<typeof updateStepStatus>[1][\"status\"]\n        })\n      );\n    default:\n      throw new Error(`Unknown tool: ${request.params.name}`);\n  }\n});\n\nasync function main() {\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n}\n\nmain().catch((error) => {\n  console.error(\"[duckwalk-mcp] fatal error\");\n  console.error(error);\n  process.exit(1);\n});\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@duckwalk/mcp-server",
+  "version": "0.1.2",
+  "description": "duckWalk MCP server for guided implementation, PR review playback, and Pathfinder walkthroughs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BashirTowdiee/DuckWalk.git",
+    "directory": "apps/mcp-server"
+  },
+  "homepage": "https://github.com/BashirTowdiee/DuckWalk/tree/main/apps/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/BashirTowdiee/DuckWalk/issues"
+  },
+  "keywords": [
+    "duckwalk",
+    "mcp",
+    "model-context-protocol",
+    "codex",
+    "pathfinder",
+    "code-review",
+    "architecture"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "duckwalk-mcp": "./dist/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@duckwalk/core": "0.1.0",
+    "@duckwalk/schema": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx watch src/server.ts",
+    "lint": "eslint . --max-warnings=0",
+    "test": "vitest run src/service.test.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}