stepwell 0.0.0-stage → 0.2.4

package/dist/resources.js

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TEMPLATE_KINDS, fileHashes, phaseContext, projectTemplates, } from "stepwell-core";
+const MARKDOWN = "text/markdown";
+const JSON_MIME = "application/json";
+function decodeRoot(raw) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function readOrThrow(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        throw new Error(`missing required file: ${path}`);
+    }
+}
+export function registerDocsResources(server) {
+    server.registerResource("templates", new ResourceTemplate("stepwell://templates/{kind}", {
+        list: () => ({
+            resources: TEMPLATE_KINDS.map((kind) => ({
+                uri: `stepwell://templates/${kind}`,
+                name: `template: ${kind}`,
+                description: "Canonical skeleton of a mandatory file (M8) — adopt unchanged.",
+                mimeType: MARKDOWN,
+            })),
+        }),
+    }), {
+        title: "Project templates",
+        description: "Canonical skeletons of the four mandatory files (M8): kind = \"backlog\" | \"progress\" | " +
+            "\"backlog-archive\" | \"progress-archive\" — the agent creates the files from these " +
+            "(variant A: read-only, no init_project).",
+        mimeType: MARKDOWN,
+    }, (uri, { kind }) => {
+        const k = String(kind);
+        if (!TEMPLATE_KINDS.includes(k)) {
+            throw new Error(`unknown template kind: ${String(kind)} (allowed: ${TEMPLATE_KINDS.join(" | ")})`);
+        }
+        return {
+            contents: [
+                { uri: uri.href, text: projectTemplates[k], mimeType: MARKDOWN },
+            ],
+        };
+    });
+    server.registerResource("backlog", new ResourceTemplate("stepwell://{root}/backlog", { list: undefined }), {
+        title: "BACKLOG.md",
+        description: "Open items of a STEPWELL project (verbatim; root percent-encoded in the URI).",
+        mimeType: MARKDOWN,
+    }, (uri, { root }) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: readOrThrow(join(decodeRoot(String(root)), "BACKLOG.md")),
+                mimeType: MARKDOWN,
+            },
+        ],
+    }));
+    server.registerResource("progress", new ResourceTemplate("stepwell://{root}/progress", { list: undefined }), {
+        title: "PROGRESS.md",
+        description: "Progress table + active phases (verbatim; root percent-encoded in the URI).",
+        mimeType: MARKDOWN,
+    }, (uri, { root }) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: readOrThrow(join(decodeRoot(String(root)), "PROGRESS.md")),
+                mimeType: MARKDOWN,
+            },
+        ],
+    }));
+    server.registerResource("hashes", new ResourceTemplate("stepwell://{root}/hashes", { list: undefined }), {
+        title: "File hashes",
+        description: "SHA256 per doc file as JSON (E2/12.5) — the client compares against the last known " +
+            "state and skips full reads when everything is unchanged (fast path E3). " +
+            "Root percent-encoded in the URI.",
+        mimeType: JSON_MIME,
+    }, (uri, { root }) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: JSON.stringify(fileHashes(decodeRoot(String(root)))),
+                mimeType: JSON_MIME,
+            },
+        ],
+    }));
+    server.registerResource("phase", new ResourceTemplate("stepwell://{root}/phase/{phase}", { list: undefined }), {
+        title: "Phase context",
+        description: "Phase verbatim + table rows + merged backlog item bodies in step order " +
+            "(G5/12.6 — composition at read time, no duplicate in the files). Search across active " +
+            "phases and archive; root and phase percent-encoded in the URI.",
+        mimeType: MARKDOWN,
+    }, (uri, { root, phase }) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: phaseContext(decodeRoot(String(root)), decodeRoot(String(phase))).markdown,
+                mimeType: MARKDOWN,
+            },
+        ],
+    }));
+    server.registerResource("archive", new ResourceTemplate("stepwell://{root}/archive/{kind}", { list: undefined }), {
+        title: "Archive",
+        description: "Append-only archives: kind = \"backlog\" (BACKLOG_ARCHIVE.md) or \"progress\" " +
+            "(PROGRESS_ARCHIVE.md); root percent-encoded in the URI.",
+        mimeType: MARKDOWN,
+    }, (uri, { root, kind }) => {
+        const archivePath = (k) => k === "backlog"
+            ? join("docs", "archive", "BACKLOG_ARCHIVE.md")
+            : k === "progress"
+                ? join("docs", "archive", "PROGRESS_ARCHIVE.md")
+                : undefined;
+        const rel = archivePath(String(kind));
+        if (rel === undefined) {
+            throw new Error(`unknown archive kind: ${String(kind)} (allowed: backlog | progress)`);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: readOrThrow(join(decodeRoot(String(root)), rel)),
+                    mimeType: MARKDOWN,
+                },
+            ],
+        };
+    });
+}

package/dist/serve.d.ts

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

package/dist/serve.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createDocsServer } from "./server.js";
+const server = createDocsServer();
+await server.connect(new StdioServerTransport());

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const SERVER_NAME = "stepwell";
+export declare const SERVER_VERSION: string;
+export declare function createDocsServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,32 @@
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { registerDocsResources } from "./resources.js";
+import { READ_ONLY_ANNOTATIONS, registerDocsTools } from "./tools.js";
+export const SERVER_NAME = "stepwell";
+// L31/38.1: derived from the workspace package.json — the release bump is the
+// package.json edit alone; the handshake version can never decouple again.
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+export const SERVER_VERSION = version;
+export function createDocsServer() {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        // M12: conditional, passive entry hint (findability without pushiness —
+        // opt-in per project, never auto-init in a foreign repo, M13 direction).
+        instructions: "STEPWELL structures the project via four markdown files (BACKLOG.md, PROGRESS.md, docs/archive/*). " +
+            "Use these tools only when the project root contains the four STEPWELL files OR the user explicitly asks for STEPWELL. " +
+            "Never create structure unrequested in a foreign repo. New to STEPWELL? Start from docs/QUICKSTART.md; " +
+            "templates are available as resources.",
+    });
+    server.registerTool("echo", {
+        title: "Echo",
+        description: "Echo tool for server verification (step 2.1).",
+        annotations: { ...READ_ONLY_ANNOTATIONS },
+        inputSchema: { text: z.string().describe("The text to return.") },
+    }, async ({ text }) => ({
+        content: [{ type: "text", text }],
+    }));
+    registerDocsTools(server);
+    registerDocsResources(server);
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,19 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Priority } from "stepwell-core";
+export declare const READ_ONLY_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+};
+export declare const DESTRUCTIVE_ANNOTATIONS: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+    readonly idempotentHint: false;
+};
+export declare const MUTATING_ANNOTATIONS: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: false;
+    readonly idempotentHint: false;
+};
+export declare function registerDocsTools(server: McpServer): void;
+export type { Priority };