@projitive/mcp 1.0.1 → 1.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 Language: English | [简体中文](README_CN.md)
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.1**
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.3**
 
 Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
@@ -50,6 +50,17 @@ taskNext
   -> taskNext (next cycle)
 ```
 
+When no actionable task exists (`actionableTasks: 0`), use bootstrap path:
+
+```text
+taskNext
+  -> projectContext
+  -> create 1-3 TODO tasks in tasks.md marker block (from roadmap/readme/report gaps)
+  -> taskNext
+```
+
+Optional customization: add `hooks/task_no_actionable.md` in governance root to override the default no-task discovery checklist.
+
 When the agent starts inside a project:
 
 ```text
@@ -58,17 +69,43 @@ projectLocate -> projectContext -> taskList -> taskContext
 
 ## Quick Start
 
+Use npm package directly in MCP client configuration:
+
 ```bash
-cd packages/mcp
-npm ci
-npm run build
-npm run test
+npx -y @projitive/mcp
+```
+
+MCP client config example (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "projitive": {
+      "command": "npx",
+      "args": ["-y", "@projitive/mcp"],
+      "env": {
+        "PROJITIVE_SCAN_ROOT_PATH": "/absolute/path/to/your/workspace",
+        "PROJITIVE_SCAN_MAX_DEPTH": "3"
+      }
+    }
+  }
+}
 ```
 
-Then configure your MCP client to run:
+Environment variables:
+
+- `PROJITIVE_SCAN_ROOT_PATH`: fallback scan root for discovery methods when `rootPath` is omitted.
+- `PROJITIVE_SCAN_MAX_DEPTH`: fallback scan depth when `maxDepth` is omitted (`0-8`, default `3`).
+
+Local path startup is not the recommended usage mode in this README.
+
+For maintainers/contributors only:
 
 ```bash
-node /absolute/path/to/packages/mcp/output/index.js
+cd packages/mcp
+npm ci
+npm run build
+npm run test
 ```
 
 ## Spec Version
@@ -332,17 +369,9 @@ node /absolute/path/to/packages/mcp/output/index.js
 
 - **Purpose**: return task detail + related evidence locations in one call (replacing `trace.references`).
 - **Input**: `projectPath`, `taskId`
-- **HOOK Injection**:
-  - If `hooks/task_get_head.md` exists, its content is prepended to result.
-  - If `hooks/task_get_footer.md` exists, its content is appended to result.
-  - Used for project-level custom guidance without changing core `taskContext` shape.
 - **Output Example (Markdown)**:
 
 ```markdown
-[hooks/task_get_head.md content (if present)]
-
----
-
 # taskContext
 
 ## Summary
@@ -354,7 +383,6 @@ node /absolute/path/to/packages/mcp/output/index.js
 - updatedAt: 2026-02-17T12:00:00.000Z
 - roadmapRefs: ROADMAP-0001
 - taskLocation: /workspace/proj-a/tasks.md#L42
-- hookStatus: head=loaded, footer=missing
 
 ## Evidence
 ### Related Artifacts
@@ -379,10 +407,6 @@ node /absolute/path/to/packages/mcp/output/index.js
 
 ## Next Call
 - taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
-
----
-
-[hooks/task_get_footer.md content (if present)]
 ```
 
 ### Roadmap Layer

package/output/helpers/artifacts/artifacts.js

@@ -0,0 +1,10 @@
+export function candidateFilesFromArtifacts(artifacts) {
+    return artifacts
+        .filter((item) => item.exists)
+        .flatMap((item) => {
+        if (item.kind === "file") {
+            return [item.path];
+        }
+        return (item.markdownFiles ?? []).map((entry) => entry.path);
+    });
+}

package/output/helpers/artifacts/artifacts.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { candidateFilesFromArtifacts } from "./artifacts.js";
+describe("candidateFilesFromArtifacts", () => {
+    it("collects existing file artifacts and markdown files from existing directories", () => {
+        const candidates = candidateFilesFromArtifacts([
+            { name: "README.md", kind: "file", path: "/a/README.md", exists: true, lineCount: 3 },
+            { name: "tasks.md", kind: "file", path: "/a/tasks.md", exists: false },
+            {
+                name: "designs",
+                kind: "directory",
+                path: "/a/designs",
+                exists: true,
+                markdownFiles: [{ path: "/a/designs/d1.md", lineCount: 10 }],
+            },
+        ]);
+        expect(candidates).toEqual(["/a/README.md", "/a/designs/d1.md"]);
+    });
+});

package/output/helpers/artifacts/index.js

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

package/output/helpers/index.js

@@ -1,3 +1,6 @@
+export * from './artifacts/index.js';
 export * from './catch/index.js';
 export * from './files/index.js';
+export * from './linter/index.js';
 export * from './markdown/index.js';
+export * from './response/index.js';

package/output/helpers/linter/codes.js

@@ -0,0 +1,25 @@
+export const TASK_LINT_CODES = {
+    DUPLICATE_ID: "TASK_DUPLICATE_ID",
+    IN_PROGRESS_OWNER_EMPTY: "TASK_IN_PROGRESS_OWNER_EMPTY",
+    DONE_LINKS_MISSING: "TASK_DONE_LINKS_MISSING",
+    BLOCKED_SUMMARY_EMPTY: "TASK_BLOCKED_SUMMARY_EMPTY",
+    UPDATED_AT_INVALID: "TASK_UPDATED_AT_INVALID",
+    ROADMAP_REFS_EMPTY: "TASK_ROADMAP_REFS_EMPTY",
+    OUTSIDE_MARKER: "TASK_OUTSIDE_MARKER",
+    LINK_TARGET_MISSING: "TASK_LINK_TARGET_MISSING",
+    HOOK_FILE_MISSING: "TASK_HOOK_FILE_MISSING",
+    FILTER_EMPTY: "TASK_FILTER_EMPTY",
+    CONTEXT_HOOK_HEAD_MISSING: "TASK_CONTEXT_HOOK_HEAD_MISSING",
+    CONTEXT_HOOK_FOOTER_MISSING: "TASK_CONTEXT_HOOK_FOOTER_MISSING",
+};
+export const ROADMAP_LINT_CODES = {
+    IDS_EMPTY: "ROADMAP_IDS_EMPTY",
+    TASKS_EMPTY: "ROADMAP_TASKS_EMPTY",
+    TASK_REFS_EMPTY: "ROADMAP_TASK_REFS_EMPTY",
+    UNKNOWN_REFS: "ROADMAP_UNKNOWN_REFS",
+    ZERO_LINKED_TASKS: "ROADMAP_ZERO_LINKED_TASKS",
+    CONTEXT_RELATED_TASKS_EMPTY: "ROADMAP_CONTEXT_RELATED_TASKS_EMPTY",
+};
+export const PROJECT_LINT_CODES = {
+    TASKS_FILE_MISSING: "PROJECT_TASKS_FILE_MISSING",
+};

package/output/helpers/linter/index.js

@@ -0,0 +1,2 @@
+export * from './linter.js';
+export * from './codes.js';

package/output/helpers/linter/linter.js

@@ -0,0 +1,6 @@
+export function renderLintSuggestions(suggestions) {
+    return suggestions.map((item) => {
+        const suffix = item.fixHint ? ` ${item.fixHint}` : "";
+        return `- [${item.code}] ${item.message}${suffix}`;
+    });
+}

package/output/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/helpers/response/index.js

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

package/output/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/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/hooks.js

@@ -30,20 +30,7 @@ async function readHookFile(filePath) {
     }
     return { ok: true, content };
 }
-export async function resolveHookForEvent(governanceDir, task, event) {
-    const taskHookPath = task.hooks[event];
-    if (taskHookPath) {
-        const resolvedTaskPath = path.resolve(governanceDir, taskHookPath);
-        const taskFile = await readHookFile(resolvedTaskPath);
-        if (taskFile.ok) {
-            return {
-                event,
-                source: "task",
-                path: resolvedTaskPath,
-                content: taskFile.content,
-            };
-        }
-    }
+export async function resolveHookForEvent(governanceDir, event) {
     const globalPath = path.join(governanceDir, "hooks", GLOBAL_EVENT_FILES[event]);
     const globalFile = await readHookFile(globalPath);
     if (globalFile.ok) {

package/output/hooks.test.js

@@ -3,7 +3,6 @@ import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 import { detectHookEvent, resolveHookForEvent } from "./hooks.js";
-import { normalizeTask } from "./tasks.js";
 const tempPaths = [];
 async function createTempDir() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));
@@ -22,30 +21,20 @@ describe("hooks module", () => {
         expect(detectHookEvent("IN_PROGRESS", "BLOCKED")).toBe("onBlocked");
         expect(detectHookEvent("BLOCKED", "TODO")).toBe(null);
     });
-    it("prefers task-level hook over global hook", async () => {
+    it("loads global hook when global file exists", async () => {
         const root = await createTempDir();
         const governanceDir = path.join(root, "gov");
         await fs.mkdir(path.join(governanceDir, "hooks"), { recursive: true });
         await fs.writeFile(path.join(governanceDir, "hooks", "on_task_assigned.md"), "global assigned", "utf-8");
-        await fs.writeFile(path.join(governanceDir, "hooks", "custom-assigned.md"), "task assigned", "utf-8");
-        const task = normalizeTask({
-            id: "TASK-0001",
-            title: "Task",
-            status: "TODO",
-            hooks: { onAssigned: "./hooks/custom-assigned.md" },
-        });
-        const hook = await resolveHookForEvent(governanceDir, task, "onAssigned");
-        expect(hook.source).toBe("task");
-        expect(hook.content).toContain("task assigned");
+        const hook = await resolveHookForEvent(governanceDir, "onAssigned");
+        expect(hook.source).toBe("global");
+        expect(hook.content).toContain("global assigned");
     });
-    it("falls back to global hook when task-level hook is missing", async () => {
+    it("returns none when global hook is missing", async () => {
         const root = await createTempDir();
         const governanceDir = path.join(root, "gov");
         await fs.mkdir(path.join(governanceDir, "hooks"), { recursive: true });
-        await fs.writeFile(path.join(governanceDir, "hooks", "on_task_completed.md"), "global completed", "utf-8");
-        const task = normalizeTask({ id: "TASK-0001", title: "Task", status: "IN_PROGRESS" });
-        const hook = await resolveHookForEvent(governanceDir, task, "onCompleted");
-        expect(hook.source).toBe("global");
-        expect(hook.content).toContain("global completed");
+        const hook = await resolveHookForEvent(governanceDir, "onCompleted");
+        expect(hook.source).toBe("none");
     });
 });

package/output/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -10,14 +11,29 @@ 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, "..", "..", "..");
+function resolveRuntimeVersion() {
+    const packageJsonPath = path.resolve(sourceDir, "..", "package.json");
+    try {
+        const raw = readFileSync(packageJsonPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // fallback handled below
+    }
+    return PROJITIVE_SPEC_VERSION;
+}
+const MCP_RUNTIME_VERSION = resolveRuntimeVersion();
 const server = new McpServer({
     name: "projitive",
-    version: PROJITIVE_SPEC_VERSION,
+    version: MCP_RUNTIME_VERSION,
     description: "Semantic Projitive MCP for project/task discovery and agent guidance with markdown-first outputs",
 });
-const currentFilePath = fileURLToPath(import.meta.url);
-const sourceDir = path.dirname(currentFilePath);
-const repoRoot = path.resolve(sourceDir, "..", "..", "..");
 function resolveRepoFile(relativePath) {
     return path.join(repoRoot, relativePath);
 }
@@ -170,7 +186,7 @@ function registerGovernancePrompts() {
             "Checklist:",
             "- Transition is valid per status machine.",
             "- links/roadmapRefs remain parseable and consistent.",
-            "- Hook paths (if any) still resolve.",
+            "- Only `hooks/task_no_actionable.md` is used as global background hook for no-task discovery.",
         ].join("\n");
         return asUserPrompt(text);
     });
@@ -200,6 +216,8 @@ 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);
 }

package/output/package.json

@@ -0,0 +1,36 @@
+{
+    "name": "@projitive/mcp",
+    "version": "1.0.3",
+    "description": "Projitive MCP Server for project and task discovery/update",
+    "license": "ISC",
+    "author": "",
+    "type": "module",
+    "bin": {
+        "mcp": "output/index.js"
+    },
+    "main": "./output/index.js",
+    "types": "./output/index.d.ts",
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "lint": "tsc -p tsconfig.json --noEmit",
+        "build": "tsc -p tsconfig.json",
+        "prepublishOnly": "npm run build",
+        "dev": "tsc -p tsconfig.json --watch"
+    },
+    "files": [
+        "output"
+    ],
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.17.5",
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@types/node": "^24.3.0",
+        "tsx": "^4.20.5",
+        "typescript": "^5.9.2",
+        "vitest": "^3.2.4"
+    }
+}