@projitive/mcp 1.0.8 → 1.1.2

package/output/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@projitive/mcp",
-    "version": "1.0.8",
+    "version": "1.1.2",
     "description": "Projitive MCP Server for project and task discovery/update",
     "license": "ISC",
     "author": "",
@@ -14,6 +14,8 @@
     },
     "scripts": {
         "test": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "benchmark": "vitest bench --run",
         "lint": "tsc -p tsconfig.json --noEmit",
         "build": "rm -rf output && tsc -p tsconfig.json",
         "prepublishOnly": "npm run build",
@@ -28,6 +30,7 @@
     },
     "devDependencies": {
         "@types/node": "^24.3.0",
+        "@vitest/coverage-v8": "^3.2.4",
         "tsx": "^4.20.5",
         "typescript": "^5.9.2",
         "vitest": "^3.2.4"

package/output/source/{helpers/catch → common}/catch.js

@@ -1,10 +1,10 @@
-// 辅助函数：检查是否为 PromiseLike
+// Helper function: check if value is PromiseLike
 function isPromiseLike(value) {
     return value != null && typeof value === 'object' && 'then' in value && typeof value.then === 'function';
 }
 /**
- * 构造成功结果对象
- * isError 始终返回 false
+ * Construct success result object
+ * isError always returns false
  */
 function createSuccess(value) {
     return {
@@ -14,8 +14,8 @@ function createSuccess(value) {
     };
 }
 /**
- * 构造失败结果对象
- * isError 始终返回 true
+ * Construct failure result object
+ * isError always returns true
  */
 function createFailure(error) {
     return {
@@ -43,6 +43,6 @@ export async function catchIt(input) {
     catch (error) {
         return createFailure(error);
     }
-    // 理论上不会到达这里，兜底类型安全
+    // Theoretically shouldn't reach here, fallback for type safety
     return createFailure(new Error('Unexpected input type'));
 }

package/output/source/{helpers/catch → common}/catch.test.js

@@ -1,39 +1,39 @@
 import { describe, it, expect } from 'vitest';
 import { catchIt } from './catch.js';
 describe('catchIt', () => {
-    it('同步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+    it('sync function should return value, error undefined, isError false', async () => {
         const result = await catchIt(() => 123);
         expect(result.value).toBe(123);
         expect(result.error).toBeUndefined();
         expect(result.isError()).toBe(false);
     });
-    it('异步函数返回值应为 value，error 为 undefined，isError 为 false', async () => {
+    it('async function should return value, error undefined, isError false', async () => {
         const result = await catchIt(async () => 456);
         expect(result.value).toBe(456);
         expect(result.error).toBeUndefined();
         expect(result.isError()).toBe(false);
     });
-    it('同步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+    it('sync throw should return error, value undefined, isError true', async () => {
         const error = new Error('fail');
         const result = await catchIt(() => { throw error; });
         expect(result.value).toBeUndefined();
         expect(result.error).toBe(error);
         expect(result.isError()).toBe(true);
     });
-    it('异步抛出异常时应返回 error，value 为 undefined，isError 为 true', async () => {
+    it('async throw should return error, value undefined, isError true', async () => {
         const error = new Error('fail-async');
         const result = await catchIt(() => Promise.reject(error));
         expect(result.value).toBeUndefined();
         expect(result.error).toBe(error);
         expect(result.isError()).toBe(true);
     });
-    it('PromiseLike resolve 时应返回 value，error 为 undefined，isError 为 false', async () => {
+    it('PromiseLike resolve should return value, error undefined, isError false', async () => {
         const result = await catchIt(Promise.resolve('ok'));
         expect(result.value).toBe('ok');
         expect(result.error).toBeUndefined();
         expect(result.isError()).toBe(false);
     });
-    it('PromiseLike reject 时应返回 error，value 为 undefined，isError 为 true', async () => {
+    it('PromiseLike reject should return error, value undefined, isError true', async () => {
         const error = new Error('promise-fail');
         const result = await catchIt(Promise.reject(error));
         expect(result.value).toBeUndefined();

package/output/source/common/errors.js

@@ -0,0 +1,120 @@
+// Projitive unified error type definitions
+export class ProjitiveError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ProjitiveError";
+    }
+}
+// Project related errors
+export class ProjectError extends ProjitiveError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = "ProjectError";
+    }
+}
+export class ProjectNotFoundError extends ProjectError {
+    constructor(inputPath) {
+        super(`Project not found at path: ${inputPath}`, "PROJECT_NOT_FOUND", {
+            inputPath,
+        });
+    }
+}
+export class GovernanceRootNotFoundError extends ProjectError {
+    constructor(projectPath) {
+        super(`Governance root not found for project: ${projectPath}`, "GOVERNANCE_ROOT_NOT_FOUND", { projectPath });
+    }
+}
+// Task related errors
+export class TaskError extends ProjitiveError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = "TaskError";
+    }
+}
+export class TaskNotFoundError extends TaskError {
+    constructor(taskId) {
+        super(`Task not found: ${taskId}`, "TASK_NOT_FOUND", { taskId });
+    }
+}
+export class InvalidTaskIdError extends TaskError {
+    constructor(taskId) {
+        super(`Invalid task ID: ${taskId}`, "INVALID_TASK_ID", { taskId });
+    }
+}
+export class TaskValidationError extends TaskError {
+    errors;
+    constructor(taskId, errors) {
+        super(`Task validation failed for ${taskId}: ${errors.join(", ")}`, "TASK_VALIDATION_FAILED", { taskId, errors });
+        this.errors = errors;
+    }
+}
+// File operation errors
+export class FileError extends ProjitiveError {
+    filePath;
+    constructor(message, filePath, code, details) {
+        super(message, code || "FILE_ERROR", { filePath, ...details });
+        this.filePath = filePath;
+        this.name = "FileError";
+    }
+}
+export class FileNotFoundError extends FileError {
+    constructor(filePath) {
+        super(`File not found: ${filePath}`, filePath, "FILE_NOT_FOUND");
+    }
+}
+export class FileReadError extends FileError {
+    constructor(filePath, cause) {
+        super(`Failed to read file: ${filePath}`, filePath, "FILE_READ_ERROR", {
+            cause: cause?.message,
+        });
+    }
+}
+export class FileWriteError extends FileError {
+    constructor(filePath, cause) {
+        super(`Failed to write file: ${filePath}`, filePath, "FILE_WRITE_ERROR", {
+            cause: cause?.message,
+        });
+    }
+}
+// Validation errors
+export class ValidationError extends ProjitiveError {
+    errors;
+    constructor(message, errors = [], code) {
+        super(message, code || "VALIDATION_FAILED", { errors });
+        this.errors = errors;
+        this.name = "ValidationError";
+    }
+}
+export class ConfidenceScoreError extends ValidationError {
+    score;
+    constructor(message, score, errors = []) {
+        super(message, errors, "CONFIDENCE_SCORE_ERROR");
+        this.score = score;
+        this.score = score;
+    }
+}
+// MCP related errors
+export class MCPError extends ProjitiveError {
+    constructor(message, code, details) {
+        super(message, code, details);
+        this.name = "MCPError";
+    }
+}
+export class ResourceNotFoundError extends MCPError {
+    constructor(resourceUri) {
+        super(`Resource not found: ${resourceUri}`, "RESOURCE_NOT_FOUND", {
+            resourceUri,
+        });
+    }
+}
+export class PromptNotFoundError extends MCPError {
+    constructor(promptName) {
+        super(`Prompt not found: ${promptName}`, "PROMPT_NOT_FOUND", {
+            promptName,
+        });
+    }
+}

package/output/source/{helpers/files → common}/files.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { catchIt } from "../catch/index.js";
+import { catchIt } from "./catch.js";
 const FILE_ARTIFACTS = ["README.md", "roadmap.md", "tasks.md"];
 const DIRECTORY_ARTIFACTS = ["designs", "reports", "hooks"];
 async function fileLineCount(filePath) {

package/output/source/{helpers/files → common}/files.test.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { discoverGovernanceArtifacts } from "./files.js";
+import { discoverGovernanceArtifacts } from './files.js';
 const tempPaths = [];
 async function createTempDir() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));

package/output/source/common/index.js

@@ -0,0 +1,9 @@
+export * from "./errors.js";
+export * from "./types.js";
+export * from "./utils.js";
+export * from "./markdown.js";
+export * from "./files.js";
+export * from "./response.js";
+export * from "./catch.js";
+export * from "./artifacts.js";
+export * from "./linter.js";

package/output/source/{helpers/linter/codes.js → common/linter.js}

@@ -1,3 +1,9 @@
+export function renderLintSuggestions(suggestions) {
+    return suggestions.map((item) => {
+        const suffix = item.fixHint ? ` ${item.fixHint}` : "";
+        return `- [${item.code}] ${item.message}${suffix}`;
+    });
+}
 export const TASK_LINT_CODES = {
     DUPLICATE_ID: "TASK_DUPLICATE_ID",
     IN_PROGRESS_OWNER_EMPTY: "TASK_IN_PROGRESS_OWNER_EMPTY",
@@ -11,6 +17,13 @@ export const TASK_LINT_CODES = {
     FILTER_EMPTY: "TASK_FILTER_EMPTY",
     CONTEXT_HOOK_HEAD_MISSING: "TASK_CONTEXT_HOOK_HEAD_MISSING",
     CONTEXT_HOOK_FOOTER_MISSING: "TASK_CONTEXT_HOOK_FOOTER_MISSING",
+    // Spec v1.1.0 - Blocker Categorization
+    BLOCKED_WITHOUT_BLOCKER: "TASK_BLOCKED_WITHOUT_BLOCKER",
+    BLOCKER_TYPE_INVALID: "TASK_BLOCKER_TYPE_INVALID",
+    BLOCKER_DESCRIPTION_EMPTY: "TASK_BLOCKER_DESCRIPTION_EMPTY",
+    IN_PROGRESS_WITHOUT_SUBSTATE: "TASK_IN_PROGRESS_WITHOUT_SUBSTATE",
+    SUBSTATE_PHASE_INVALID: "TASK_SUBSTATE_PHASE_INVALID",
+    SUBSTATE_CONFIDENCE_INVALID: "TASK_SUBSTATE_CONFIDENCE_INVALID",
 };
 export const ROADMAP_LINT_CODES = {
     IDS_EMPTY: "ROADMAP_IDS_EMPTY",

package/output/source/{helpers/markdown → common}/markdown.test.js

@@ -2,7 +2,7 @@ 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";
+import { findTextReferences, readMarkdownSections } from './markdown.js';
 const tempPaths = [];
 async function createTempDir() {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "projitive-mcp-test-"));

package/output/source/{helpers/response → common}/response.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { asText, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from "./response.js";
+import { asText, nextCallSection, renderErrorMarkdown, renderToolResponseMarkdown, summarySection, } from './response.js';
 describe("response helpers", () => {
     it("wraps markdown text as MCP text content", () => {
         const result = asText("# hello");

package/output/source/common/types.js

@@ -0,0 +1,7 @@
+// Common type definitions (simplified)
+export const VALID_STATUS_TRANSITIONS = {
+    TODO: ["IN_PROGRESS"],
+    IN_PROGRESS: ["TODO", "BLOCKED", "DONE"],
+    BLOCKED: ["IN_PROGRESS"],
+    DONE: [],
+};

package/output/source/common/utils.js

@@ -0,0 +1,39 @@
+// Common utility functions
+import fs from "node:fs/promises";
+import path from "node:path";
+/**
+ * Safely read Markdown file content, return fallback if file doesn't exist or is empty
+ */
+export async function readMarkdownOrFallback(relativePath, fallbackTitle, repoRoot = process.cwd()) {
+    const absolutePath = path.resolve(repoRoot, relativePath);
+    try {
+        const content = await fs.readFile(absolutePath, "utf-8");
+        if (content.trim().length > 0) {
+            return content;
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            console.error(`Failed to read file: ${absolutePath}`, error);
+        }
+    }
+    return [
+        `# ${fallbackTitle}`,
+        "",
+        `- file: ${relativePath}`,
+        "- status: missing-or-empty",
+        "- next: create this file or ensure it has readable markdown content",
+    ].join("\n");
+}
+/**
+ * Capitalize first letter
+ */
+export function capitalizeFirstLetter(str) {
+    return str.split(/[-_]/).map(part => part.charAt(0).toUpperCase() + part.slice(1)).join('');
+}
+/**
+ * Format title
+ */
+export function formatTitle(str) {
+    return str.split(/[-_]/).map(part => part.charAt(0).toUpperCase() + part.slice(1)).join(' ');
+}

package/output/source/index.js

@@ -1,17 +1,14 @@
 #!/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";
-import { registerDesignContextResources, registerDesignContextPrompts } from "./design-context.js";
-const PROJITIVE_SPEC_VERSION = "1.0.0";
+import { registerTools } from "./tools/index.js";
+import { registerPrompts } from "./prompts/index.js";
+import { registerResources } from "./resources/index.js";
+const PROJITIVE_SPEC_VERSION = "1.1.0";
 const currentFilePath = fileURLToPath(import.meta.url);
 const sourceDir = path.dirname(currentFilePath);
 const repoRoot = path.resolve(sourceDir, "..", "..", "..");
@@ -23,195 +20,10 @@ const server = new McpServer({
     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",
-        "",
-        "## Start Here",
-        "- Unknown project path: `projectScan` -> `projectLocate` -> `projectContext` -> `taskNext`.",
-        "- Known project path: `projectContext` -> `taskNext` (or `taskList`) -> `taskContext`.",
-        "- Need to bootstrap governance: call `projectInit(projectPath=\"<project-dir>\")` only when `.projitive` is missing.",
-        "",
-        "## Methods",
-        "| Order | Group | Method | Agent Use |",
-        "|---|---|---|---|",
-        "| 1 | Project | projectScan | discover governance roots when project is unknown |",
-        "| 2 | Project | projectLocate | lock nearest governance root from any path |",
-        "| 3 | Project | projectContext | load project summary before task decisions |",
-        "| 4 | Task | taskNext | auto-pick highest-priority actionable task |",
-        "| 5 | Task | taskList | list/filter tasks for manual selection |",
-        "| 6 | Task | taskContext | inspect one task with evidence and read order |",
-        "| 7 | Roadmap | roadmapList | inspect roadmap-task linkage |",
-        "| 8 | Roadmap | roadmapContext | inspect one roadmap with references |",
-        "| 9 | Project | projectNext | rank actionable projects across workspace |",
-        "| 10 | Project | projectInit | bootstrap governance files if missing |"
-    ].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: "Primary execution prompt: select one task, execute, and verify evidence consistency",
-        argsSchema: {
-            projectPath: z.string().optional(),
-            taskId: z.string().optional(),
-        },
-    }, async ({ projectPath, taskId }) => {
-        const taskEntry = taskId && projectPath
-            ? `1) Run taskContext(projectPath=\"${projectPath}\", taskId=\"${taskId}\").`
-            : "1) Run taskNext().";
-        const text = [
-            "You are executing Projitive governance workflow in agent-first mode.",
-            "",
-            "Fast path:",
-            taskEntry,
-            "2) Follow Suggested Read Order and identify execution blockers.",
-            "3) Edit governance markdown only (tasks/designs/reports/roadmap).",
-            "4) Re-run taskContext for the selected task and verify references.",
-            "",
-            "Fallbacks:",
-            "- If `.projitive` is missing for a known project, run `projectInit(projectPath=\"<project-dir>\")` first.",
-            "- If taskNext returns no actionable task, follow its no-task checklist and create 1-3 TODO tasks.",
-            "- If project is unknown, run projectScan -> projectLocate -> projectContext before task tools.",
-            "",
-            "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: "Safe status transition playbook with mandatory evidence backfill",
-        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 with evidence alignment.",
-            "",
-            `1) Run taskContext(projectPath=\"${projectPath}\", taskId=\"${taskId}\").`,
-            `2) Confirm transition to ${targetStatus} is valid.`,
-            "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.",
-            "6) If lint remains, fix and re-run taskContext once more.",
-            "",
-            "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: "Discovery-first triage prompt to pick project and next executable task",
-        argsSchema: {},
-    }, async () => {
-        const text = [
-            "Triage governance and pick one execution target quickly.",
-            "",
-            "0) If known project has no `.projitive`, run projectInit(projectPath=<project-dir>) first.",
-            "1) If project path is unknown, run projectScan() and pick one discovered project.",
-            "2) Run projectNext() to rank projects.",
-            "3) Run projectContext(projectPath=<selectedProject>).",
-            "4) Run taskNext() for best actionable task.",
-            "5) If manual filtering is needed, run taskList(projectPath=<selectedProject>, status=IN_PROGRESS).",
-            "6) Continue with taskContext(projectPath=<selectedProject>, taskId=<selectedTaskId>).",
-        ].join("\n");
-        return asUserPrompt(text);
-    });
-}
-registerProjectTools(server);
-registerTaskTools(server);
-registerRoadmapTools(server);
-registerGovernanceResources();
-registerGovernancePrompts();
-registerDesignContextResources(server);
-registerDesignContextPrompts(server);
+// 注册所有模块
+registerTools(server);
+registerPrompts(server);
+registerResources(server, repoRoot);
 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}`);