@projitive/mcp 1.0.2 → 1.0.4

package/output/source/helpers/linter/linter.test.js

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { renderLintSuggestions } from "./linter.js";
+describe("renderLintSuggestions", () => {
+    it("renders lint lines with code and message", () => {
+        const lines = renderLintSuggestions([
+            { code: "TASK_001", message: "Example lint" },
+        ]);
+        expect(lines).toEqual(["- [TASK_001] Example lint"]);
+    });
+    it("appends fixHint when provided", () => {
+        const lines = renderLintSuggestions([
+            { code: "TASK_002", message: "Missing field.", fixHint: "Set owner." },
+        ]);
+        expect(lines).toEqual(["- [TASK_002] Missing field. Set owner."]);
+    });
+});

package/output/source/helpers/markdown/index.js

@@ -0,0 +1 @@
+export * from './markdown.js';

package/output/source/helpers/markdown/markdown.js

@@ -0,0 +1,33 @@
+import fs from "node:fs/promises";
+export async function readMarkdownSections(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const headers = [];
+    lines.forEach((line, index) => {
+        const match = line.match(/^(#{1,6})\s+(.+)$/);
+        if (match) {
+            headers.push({ level: match[1].length, heading: match[2].trim(), startLine: index + 1 });
+        }
+    });
+    const sections = headers.map((header, index) => {
+        const next = headers[index + 1];
+        return {
+            heading: header.heading,
+            level: header.level,
+            startLine: header.startLine,
+            endLine: next ? next.startLine - 1 : lines.length,
+        };
+    });
+    return { filePath, lineCount: lines.length, sections };
+}
+export async function findTextReferences(filePath, needle) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const result = [];
+    lines.forEach((line, index) => {
+        if (line.includes(needle)) {
+            result.push({ filePath, line: index + 1, text: line.trim() });
+        }
+    });
+    return result;
+}

package/output/source/helpers/markdown/markdown.test.js

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { findTextReferences, readMarkdownSections } from "./markdown.js";
+const tempPaths = [];
+async function createTempDir() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));
+    tempPaths.push(dir);
+    return dir;
+}
+afterEach(async () => {
+    await Promise.all(tempPaths.splice(0).map(async (dir) => {
+        await fs.rm(dir, { recursive: true, force: true });
+    }));
+});
+describe("markdown module", () => {
+    it("locates markdown sections with line ranges", async () => {
+        const root = await createTempDir();
+        const file = path.join(root, "tasks.md");
+        await fs.writeFile(file, ["# Tasks", "", "## TODO", "- TASK-0001", "## DONE", "- TASK-0002"].join("\n"), "utf-8");
+        const located = await readMarkdownSections(file);
+        expect(located.lineCount).toBe(6);
+        expect(located.sections[0].heading).toBe("Tasks");
+        expect(located.sections[1].heading).toBe("TODO");
+        expect(located.sections[1].startLine).toBe(3);
+    });
+    it("finds ID references with exact line number", async () => {
+        const root = await createTempDir();
+        const file = path.join(root, "reports.md");
+        await fs.writeFile(file, ["Task: TASK-0001", "Roadmap: ROADMAP-0001"].join("\n"), "utf-8");
+        const refs = await findTextReferences(file, "TASK-0001");
+        expect(refs).toHaveLength(1);
+        expect(refs[0].line).toBe(1);
+    });
+});

package/output/source/helpers/response/index.js

@@ -0,0 +1 @@
+export * from "./response.js";

package/output/source/helpers/response/response.js

@@ -0,0 +1,73 @@
+export function asText(markdown) {
+    return {
+        content: [{ type: "text", text: markdown }],
+    };
+}
+function withFallback(lines) {
+    return lines.length > 0 ? lines : ["- (none)"];
+}
+function shouldKeepRawLine(trimmed) {
+    if (trimmed.length === 0) {
+        return true;
+    }
+    if (trimmed.startsWith("#") || trimmed.startsWith(">") || trimmed.startsWith("```")) {
+        return true;
+    }
+    if (/^[-*+]\s/.test(trimmed)) {
+        return true;
+    }
+    if (/^\d+\.\s/.test(trimmed)) {
+        return true;
+    }
+    return false;
+}
+function normalizeLine(line) {
+    const trimmed = line.trim();
+    if (shouldKeepRawLine(trimmed)) {
+        return line;
+    }
+    return `- ${trimmed}`;
+}
+function normalizeLines(lines) {
+    return lines.map((line) => normalizeLine(line));
+}
+export function section(title, lines) {
+    return { title, lines: normalizeLines(lines) };
+}
+export function summarySection(lines) {
+    return section("Summary", lines);
+}
+export function evidenceSection(lines) {
+    return section("Evidence", lines);
+}
+export function guidanceSection(lines) {
+    return section("Agent Guidance", lines);
+}
+export function lintSection(lines) {
+    return section("Lint Suggestions", lines);
+}
+export function nextCallSection(nextCall) {
+    return section("Next Call", nextCall ? [nextCall] : []);
+}
+export function renderToolResponseMarkdown(payload) {
+    const body = payload.sections.flatMap((section) => [
+        `## ${section.title}`,
+        ...withFallback(section.lines),
+        "",
+    ]);
+    return [
+        `# ${payload.toolName}`,
+        "",
+        ...body,
+    ].join("\n").trimEnd();
+}
+export function renderErrorMarkdown(toolName, cause, nextSteps, retryExample) {
+    return renderToolResponseMarkdown({
+        toolName,
+        sections: [
+            section("Error", [`cause: ${cause}`]),
+            section("Next Step", nextSteps),
+            section("Retry Example", [retryExample ?? "(none)"]),
+        ],
+    });
+}

package/output/source/helpers/response/response.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { asText, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./response.js";
+describe("response helpers", () => {
+    it("wraps markdown text as MCP text content", () => {
+        const result = asText("# hello");
+        expect(result.content).toEqual([{ type: "text", text: "# hello" }]);
+    });
+    it("renders error markdown sections", () => {
+        const markdown = renderErrorMarkdown("taskContext", "bad id", ["retry"], "taskContext(...)");
+        expect(markdown).toContain("# taskContext");
+        expect(markdown).toContain("## Error");
+        expect(markdown).toContain("- cause: bad id");
+        expect(markdown).toContain("- retry");
+        expect(markdown).toContain("## Retry Example");
+    });
+    it("renders standard tool response sections with fallback", () => {
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                { title: "Summary", lines: ["- governanceDir: /tmp/.projitive"] },
+                { title: "Evidence", lines: [] },
+            ],
+        });
+        expect(markdown).toContain("# taskList");
+        expect(markdown).toContain("## Summary");
+        expect(markdown).toContain("## Evidence");
+        expect(markdown).toContain("- (none)");
+    });
+    it("auto-prefixes plain lines in section helpers", () => {
+        const markdown = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [
+                summarySection(["governanceDir: /tmp/.projitive"]),
+            ],
+        });
+        expect(markdown).toContain("- governanceDir: /tmp/.projitive");
+    });
+    it("nextCallSection accepts optional call and falls back when missing", () => {
+        const withCall = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [nextCallSection("taskContext(projectPath=\"/tmp\", taskId=\"TASK-0001\")")],
+        });
+        expect(withCall).toContain("- taskContext(projectPath=\"/tmp\", taskId=\"TASK-0001\")");
+        const withoutCall = renderToolResponseMarkdown({
+            toolName: "taskList",
+            sections: [nextCallSection(undefined)],
+        });
+        expect(withoutCall).toContain("- (none)");
+    });
+});

package/output/source/index.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import packageJson from "../package.json" with { type: "json" };
+import { registerProjectTools } from "./projitive.js";
+import { registerTaskTools } from "./tasks.js";
+import { registerRoadmapTools } from "./roadmap.js";
+const PROJITIVE_SPEC_VERSION = "1.0.0";
+const currentFilePath = fileURLToPath(import.meta.url);
+const sourceDir = path.dirname(currentFilePath);
+const repoRoot = path.resolve(sourceDir, "..", "..", "..");
+const MCP_RUNTIME_VERSION = typeof packageJson.version === "string" && packageJson.version.trim().length > 0
+    ? packageJson.version.trim()
+    : PROJITIVE_SPEC_VERSION;
+const server = new McpServer({
+    name: "projitive",
+    version: MCP_RUNTIME_VERSION,
+    description: "Semantic Projitive MCP for project/task discovery and agent guidance with markdown-first outputs",
+});
+function resolveRepoFile(relativePath) {
+    return path.join(repoRoot, relativePath);
+}
+async function readMarkdownOrFallback(relativePath, fallbackTitle) {
+    const absolutePath = resolveRepoFile(relativePath);
+    const content = await fs.readFile(absolutePath, "utf-8").catch(() => undefined);
+    if (typeof content === "string" && content.trim().length > 0) {
+        return content;
+    }
+    return [
+        `# ${fallbackTitle}`,
+        "",
+        `- file: ${relativePath}`,
+        "- status: missing-or-empty",
+        "- next: create this file or ensure it has readable markdown content",
+    ].join("\n");
+}
+function renderMethodCatalogMarkdown() {
+    return [
+        "# MCP Method Catalog",
+        "",
+        "## Core Pattern",
+        "- Prefer List/Context for primary discovery/detail flows.",
+        "- Use Next/Scan/Locate for acceleration and bootstrapping.",
+        "",
+        "## Methods",
+        "| Group | Method | Role |",
+        "|---|---|---|",
+        "| Project | projectInit | initialize governance directory structure |",
+        "| Project | projectScan | discover governance projects by marker |",
+        "| Project | projectNext | rank actionable projects |",
+        "| Project | projectLocate | resolve nearest governance root |",
+        "| Project | projectContext | summarize project governance context |",
+        "| Task | taskList | list tasks with optional filters |",
+        "| Task | taskNext | select top actionable task |",
+        "| Task | taskContext | inspect one task with references |",
+        "| Roadmap | roadmapList | list roadmap IDs and linked tasks |",
+        "| Roadmap | roadmapContext | inspect one roadmap with references |",
+    ].join("\n");
+}
+function registerGovernanceResources() {
+    server.registerResource("governanceWorkspace", "projitive://governance/workspace", {
+        title: "Governance Workspace",
+        description: "Primary governance README under .projitive",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://governance/workspace",
+                text: await readMarkdownOrFallback(".projitive/README.md", "Governance Workspace"),
+            },
+        ],
+    }));
+    server.registerResource("governanceTasks", "projitive://governance/tasks", {
+        title: "Governance Tasks",
+        description: "Current task pool and status under .projitive/tasks.md",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://governance/tasks",
+                text: await readMarkdownOrFallback(".projitive/tasks.md", "Governance Tasks"),
+            },
+        ],
+    }));
+    server.registerResource("governanceRoadmap", "projitive://governance/roadmap", {
+        title: "Governance Roadmap",
+        description: "Current roadmap under .projitive/roadmap.md",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://governance/roadmap",
+                text: await readMarkdownOrFallback(".projitive/roadmap.md", "Governance Roadmap"),
+            },
+        ],
+    }));
+    server.registerResource("mcpMethodCatalog", "projitive://mcp/method-catalog", {
+        title: "MCP Method Catalog",
+        description: "Method naming and purpose map for agent routing",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "projitive://mcp/method-catalog",
+                text: renderMethodCatalogMarkdown(),
+            },
+        ],
+    }));
+}
+function asUserPrompt(text) {
+    return {
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text,
+                },
+            },
+        ],
+    };
+}
+function registerGovernancePrompts() {
+    server.registerPrompt("executeTaskWorkflow", {
+        title: "Execute Task Workflow",
+        description: "Guide an agent through taskNext -> taskContext -> artifact update -> verification",
+        argsSchema: {
+            rootPath: z.string().optional(),
+            projectPath: z.string().optional(),
+            taskId: z.string().optional(),
+        },
+    }, async ({ rootPath, projectPath, taskId }) => {
+        const text = [
+            "You are executing Projitive governance workflow.",
+            "",
+            "Execution order:",
+            taskId && projectPath
+                ? `1) Run taskContext(projectPath=\"${projectPath}\", taskId=\"${taskId}\").`
+                : `1) Run taskNext(${rootPath ? `rootPath=\"${rootPath}\"` : ""}).`,
+            "2) Read Suggested Read Order and collect blocking gaps.",
+            "3) Update markdown artifacts only (tasks/designs/reports/roadmap as needed).",
+            "4) Re-run taskContext for the selected task and verify references are consistent.",
+            "",
+            "Hard rules:",
+            "- Keep TASK/ROADMAP IDs immutable.",
+            "- Every status transition must have report evidence.",
+            "- Do not introduce non-governance file edits unless task scope requires.",
+        ].join("\n");
+        return asUserPrompt(text);
+    });
+    server.registerPrompt("updateTaskStatusWithEvidence", {
+        title: "Update Task Status With Evidence",
+        description: "Template for safe task status transitions and evidence alignment",
+        argsSchema: {
+            projectPath: z.string(),
+            taskId: z.string(),
+            targetStatus: z.enum(["TODO", "IN_PROGRESS", "BLOCKED", "DONE"]),
+        },
+    }, async ({ projectPath, taskId, targetStatus }) => {
+        const text = [
+            "Perform a safe task status update using Projitive rules.",
+            "",
+            `1) Run taskContext(projectPath=\"${projectPath}\", taskId=\"${taskId}\").`,
+            `2) Plan status transition toward ${targetStatus}.`,
+            "3) Update tasks.md status and updatedAt.",
+            "4) Add or update a report under reports/ with concrete evidence.",
+            "5) Re-run taskContext and confirm status/evidence/reference consistency.",
+            "",
+            "Checklist:",
+            "- Transition is valid per status machine.",
+            "- links/roadmapRefs remain parseable and consistent.",
+            "- Only `hooks/task_no_actionable.md` is used as global background hook for no-task discovery.",
+        ].join("\n");
+        return asUserPrompt(text);
+    });
+    server.registerPrompt("triageProjectGovernance", {
+        title: "Triage Project Governance",
+        description: "Template to inspect a project and select next actionable governance task",
+        argsSchema: {
+            rootPath: z.string().optional(),
+        },
+    }, async ({ rootPath }) => {
+        const text = [
+            "Triage governance across projects and pick execution target.",
+            "",
+            `1) Run projectNext(${rootPath ? `rootPath=\"${rootPath}\"` : ""}).`,
+            "2) Select top ranked project.",
+            "3) Run projectContext(projectPath=<selectedProject>).",
+            "4) Run taskList(projectPath=<selectedProject>, status=IN_PROGRESS).",
+            "5) If none, run taskNext to select TODO/IN_PROGRESS candidate.",
+            "6) Continue with taskContext for detailed evidence mapping.",
+        ].join("\n");
+        return asUserPrompt(text);
+    });
+}
+registerTaskTools(server);
+registerProjectTools(server);
+registerRoadmapTools(server);
+registerGovernanceResources();
+registerGovernancePrompts();
+async function main() {
+    console.error(`[projitive-mcp] starting server`);
+    console.error(`[projitive-mcp] version=${MCP_RUNTIME_VERSION} spec=${PROJITIVE_SPEC_VERSION} transport=stdio pid=${process.pid}`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+void main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});