@projitive/mcp 1.0.0-beta.1

package/README.md

@@ -0,0 +1,318 @@
+# @projitive/mcp
+
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.0**
+
+Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现项目、发现任务、定位证据，并按治理流程推进。
+
+## 规范版本
+
+- 当前遵循规范版本：`projitive-spec v1.0.0`
+- 说明：Projitive 是通用治理规范，MCP 只是该规范的一种工具实现。
+- 对齐规则：MCP 的主版本必须与规范主版本一致（当前均为 `v1.x`）
+
+## 设计边界
+
+- MCP 负责：发现、定位、汇总、推进指导。
+- AI 负责：读取与更新 Markdown 正文内容。
+- MCP 不提供：`task.update_*`、`roadmap.update_*`、`sync_*` 这类直接写入治理工件的方法。
+- 所有工具返回内容：面向 Agent 的 Markdown（不是 JSON 对象）。
+- 输出结构统一为：`Summary` / `Evidence` / `Agent Guidance`。
+- 错误结构统一为：`Error` / `Next Step`。
+
+## Tools Methods
+
+### 发现层
+
+#### `project.next`
+
+- **作用**：直接拉取最近可推进的项目（按可执行任务数和最近更新时间排序）。
+- **输入**：`rootPath?`、`maxDepth?`、`limit?`
+- **输出示例（Markdown）**：
+
+```markdown
+# project.next
+
+## Summary
+- rootPath: /workspace
+- maxDepth: 3
+- matchedProjects: 8
+- actionableProjects: 3
+- limit: 10
+
+## Evidence
+- rankedProjects:
+1. /workspace/proj-a | actionable=5 | in_progress=2 | todo=3 | blocked=1 | done=4 | latest=2026-02-17T12:00:00.000Z | tasksPath=/workspace/proj-a/tasks.md
+2. /workspace/proj-b | actionable=3 | in_progress=1 | todo=2 | blocked=0 | done=7 | latest=2026-02-16T09:00:00.000Z | tasksPath=/workspace/proj-b/tasks.md
+
+## Agent Guidance
+- Pick top 1 project and call `project.overview` with its governanceDir.
+- Then call `task.list` and `task.get` to continue execution.
+```
+
+#### `project.scan`
+
+- **作用**：扫描目录并发现可治理项目。
+- **输入**：`rootPath?`、`maxDepth?`
+- **输出示例（Markdown）**：
+
+```markdown
+# project.scan
+
+## Summary
+- rootPath: /workspace
+- maxDepth: 3
+- discoveredCount: 2
+
+## Evidence
+- projects:
+1. /workspace/proj-a
+2. /workspace/proj-b
+
+## Agent Guidance
+- Next: call `project.locate` with one target path to lock the active governance root.
+- Then: call `project.overview` to view artifact and task status.
+```
+
+#### `project.locate`
+
+- **作用**：当 Agent 已经在某个项目目录内时，向上定位最近 `.projitive`，确定当前项目治理根目录。
+- **输入**：`inputPath`
+- **输出示例（Markdown）**：
+
+```markdown
+# project.locate
+
+## Summary
+- resolvedFrom: /workspace/proj-a/packages/mcp
+- governanceDir: /workspace/proj-a
+- markerPath: /workspace/proj-a/.projitive
+
+## Agent Guidance
+- Next: call `project.overview` with this governanceDir to get task and roadmap summaries.
+```
+
+#### `project.overview`
+
+- **作用**：自动汇总治理状态，而不是只返回文件列表。
+- **输入**：`projectPath`
+- **输出示例（Markdown）**：
+
+```markdown
+# project.overview
+
+## Summary
+- governanceDir: /workspace/proj-a
+- tasksFile: /workspace/proj-a/tasks.md
+- roadmapIds: 3
+
+## Evidence
+### Task Summary
+- total: 12
+- TODO: 4
+- IN_PROGRESS: 3
+- BLOCKED: 1
+- DONE: 4
+
+### Artifacts
+- ✅ README.md
+- ✅ roadmap.md
+- ✅ tasks.md
+- ✅ designs/
+- ✅ reports/
+- ✅ hooks/
+
+## Agent Guidance
+- Next: call `task.list` to choose a target task.
+- Then: call `task.get` with a task ID to retrieve evidence locations and reading order.
+```
+
+### 任务层
+
+#### `task.next`
+
+- **作用**：一步完成“发现项目 + 选择最可推进任务 + 返回证据定位与阅读顺序”，用于 Agent 直接开工。
+- **输入**：`rootPath?`、`maxDepth?`、`topCandidates?`
+- **输出示例（Markdown）**：
+
+```markdown
+# task.next
+
+## Summary
+- rootPath: /workspace
+- maxDepth: 3
+- matchedProjects: 8
+- actionableTasks: 12
+- selectedProject: /workspace/proj-a
+- selectedTaskId: TASK-0003
+- selectedTaskStatus: IN_PROGRESS
+
+## Evidence
+### Selected Task
+- id: TASK-0003
+- title: Build MCP tools
+- taskLocation: /workspace/proj-a/tasks.md#L42
+
+### Top Candidates
+1. TASK-0003 | IN_PROGRESS | Build MCP tools | project=/workspace/proj-a | projectScore=6
+2. TASK-0007 | TODO | Add docs examples | project=/workspace/proj-b | projectScore=5
+
+### Suggested Read Order
+1. /workspace/proj-a/tasks.md
+2. /workspace/proj-a/designs/mcp-design.md
+3. /workspace/proj-a/reports/mcp-progress.md
+
+## Agent Guidance
+- Start immediately with Suggested Read Order and execute the selected task.
+- Re-run `task.get` for the selectedTaskId after edits to verify evidence consistency.
+```
+
+- **推荐路径**：优先调用 `task.next`，避免 `project.next -> project.overview -> task.list -> task.get` 的多跳链路。
+
+#### `task.list`
+
+- **作用**：返回当前项目任务清单，支持按状态过滤与排序。
+- **输入**：`projectPath`、`status?`、`limit?`
+- **输出示例（Markdown）**：
+
+```markdown
+# task.list
+
+## Summary
+- governanceDir: /workspace/proj-a
+- tasksPath: /workspace/proj-a/tasks.md
+- filter.status: IN_PROGRESS
+- returned: 2
+
+## Evidence
+- tasks:
+- TASK-0003 | IN_PROGRESS | Build MCP tools | owner=alice | updatedAt=2026-02-17T12:00:00.000Z
+- TASK-0007 | IN_PROGRESS | Add docs examples | owner=bob | updatedAt=2026-02-17T13:30:00.000Z
+
+## Agent Guidance
+- Next: pick one task ID and call `task.get`.
+```
+
+#### `task.get`
+
+- **作用**：基于任务 ID 一次性返回任务详情 + 关联证据位置（替代 `trace.references`）。
+- **输入**：`projectPath`、`taskId`
+- **HOOKS 注入**：
+  - 若存在 `hooks/task_get_head.md`，其内容会自动追加到返回结果最前面。
+  - 若存在 `hooks/task_get_footer.md`，其内容会自动追加到返回结果最后面。
+  - 用于给 Agent 注入项目级自定义提示，不改变 task.get 核心结构。
+- **输出示例（Markdown）**：
+
+```markdown
+[hooks/task_get_head.md 内容（如果存在）]
+
+---
+
+# task.get
+
+## Summary
+- governanceDir: /workspace/proj-a
+- taskId: TASK-0003
+- title: Build MCP tools
+- status: IN_PROGRESS
+- owner: alice
+- 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
+- /workspace/proj-a/tasks.md
+- /workspace/proj-a/designs/mcp-design.md
+- /workspace/proj-a/reports/mcp-progress.md
+
+### Reference Locations
+- /workspace/proj-a/tasks.md#L42: "id": "TASK-0003"
+- /workspace/proj-a/designs/mcp-design.md#L18: Ref: TASK-0003
+
+### Suggested Read Order
+1. /workspace/proj-a/tasks.md
+2. /workspace/proj-a/designs/mcp-design.md
+3. /workspace/proj-a/reports/mcp-progress.md
+
+## Agent Guidance
+- Read the files in Suggested Read Order.
+- Verify whether current status and evidence are consistent.
+
+---
+
+[hooks/task_get_footer.md 内容（如果存在）]
+```
+
+### 路线层
+
+#### `roadmap.list`
+
+- **作用**：列出路线图项目及其关联任务概览。
+- **输入**：`projectPath`
+- **输出示例（Markdown）**：
+
+```markdown
+# roadmap.list
+
+## Summary
+- governanceDir: /workspace/proj-a
+- roadmapCount: 2
+
+## Evidence
+- roadmaps:
+- ROADMAP-0001 | linkedTasks=6
+- ROADMAP-0002 | linkedTasks=3
+
+## Agent Guidance
+- Next: call `roadmap.get` with a roadmap ID to inspect references and related tasks.
+```
+
+#### `roadmap.get`
+
+- **作用**：获取单个路线图详情与证据定位信息。
+- **输入**：`projectPath`、`roadmapId`
+- **输出示例（Markdown）**：
+
+```markdown
+# roadmap.get
+
+## Summary
+- governanceDir: /workspace/proj-a
+- roadmapId: ROADMAP-0001
+- relatedTasks: 6
+- references: 9
+
+## Evidence
+### Related Tasks
+- TASK-0001 | DONE | Bootstrap governance
+- TASK-0003 | IN_PROGRESS | Build MCP tools
+
+### Reference Locations
+- /workspace/proj-a/roadmap.md#L21: ROADMAP-0001
+- /workspace/proj-a/tasks.md#L42: "roadmapRefs": ["ROADMAP-0001"]
+
+## Agent Guidance
+- Read roadmap references first, then related tasks.
+- Keep ROADMAP/TASK IDs unchanged while updating markdown files.
+```
+
+## 统一错误输出示例
+
+```markdown
+# task.get
+
+## Error
+- cause: Invalid task ID format: TASK-12
+
+## Next Step
+- expected format: TASK-0001
+- retry with a valid task ID
+```
+
+## Agent 推荐调用流程
+
+1. `task.next`：一步发现并选择最可推进任务，直接开工（默认路径）。
+2. `task.get`：在需要更完整上下文时，按 taskId 拉取详细证据。
+3. `project.next`：仅在需要“先选项目、再选任务”的项目级调度场景使用（可选）。
+4. 当 Agent 已在项目内时，用 `project.locate` 快速定位当前项目治理根目录。

package/output/designs.js

@@ -0,0 +1,38 @@
+import { isValidRoadmapId } from "./roadmap.js";
+import { isValidTaskId } from "./tasks.js";
+export function parseDesignMetadata(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const metadata = {};
+    for (const line of lines) {
+        const [rawKey, ...rawValue] = line.split(":");
+        if (!rawKey || rawValue.length === 0) {
+            continue;
+        }
+        const key = rawKey.trim().toLowerCase();
+        const value = rawValue.join(":").trim();
+        if (key === "task")
+            metadata.task = value;
+        if (key === "roadmap")
+            metadata.roadmap = value;
+        if (key === "owner")
+            metadata.owner = value;
+        if (key === "status")
+            metadata.status = value;
+        if (key === "last updated")
+            metadata.lastUpdated = value;
+    }
+    return metadata;
+}
+export function validateDesignMetadata(metadata) {
+    const errors = [];
+    if (!metadata.task) {
+        errors.push("Missing Task metadata");
+    }
+    else if (!isValidTaskId(metadata.task)) {
+        errors.push(`Invalid Task metadata format: ${metadata.task}`);
+    }
+    if (metadata.roadmap && !isValidRoadmapId(metadata.roadmap)) {
+        errors.push(`Invalid Roadmap metadata format: ${metadata.roadmap}`);
+    }
+    return { ok: errors.length === 0, errors };
+}

package/output/helpers/catch/catch.js

@@ -0,0 +1,48 @@
+// 辅助函数：检查是否为 PromiseLike
+function isPromiseLike(value) {
+    return value != null && typeof value === 'object' && 'then' in value && typeof value.then === 'function';
+}
+/**
+ * 构造成功结果对象
+ * isError 始终返回 false
+ */
+function createSuccess(value) {
+    return {
+        value,
+        error: undefined,
+        isError() { return false; }
+    };
+}
+/**
+ * 构造失败结果对象
+ * isError 始终返回 true
+ */
+function createFailure(error) {
+    return {
+        error,
+        value: undefined,
+        isError() { return true; }
+    };
+}
+export async function catchIt(input) {
+    try {
+        if (isPromiseLike(input)) {
+            const result = await Promise.resolve(input);
+            return createSuccess(result);
+        }
+        else if (typeof input === 'function') {
+            const result = input();
+            if (isPromiseLike(result)) {
+                return catchIt(result);
+            }
+            else {
+                return createSuccess(result);
+            }
+        }
+    }
+    catch (error) {
+        return createFailure(error);
+    }
+    // 理论上不会到达这里，兜底类型安全
+    return createFailure(new Error('Unexpected input type'));
+}

package/output/helpers/catch/catch.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { catchIt } from './catch.js';
+describe('catchIt', () => {
+    it('同步函数返回值应为 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 () => {
+        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 () => {
+        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 () => {
+        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 () => {
+        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 () => {
+        const error = new Error('promise-fail');
+        const result = await catchIt(Promise.reject(error));
+        expect(result.value).toBeUndefined();
+        expect(result.error).toBe(error);
+        expect(result.isError()).toBe(true);
+    });
+});

package/output/helpers/catch/index.js

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

package/output/helpers/files/files.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { catchIt } from "../catch/index.js";
+const FILE_ARTIFACTS = ["README.md", "roadmap.md", "tasks.md"];
+const DIRECTORY_ARTIFACTS = ["designs", "reports", "hooks"];
+async function fileLineCount(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    if (!content) {
+        return 0;
+    }
+    return content.split(/\r?\n/).length;
+}
+async function listMarkdownFiles(dirPath) {
+    const entriesResult = await catchIt(fs.readdir(dirPath, { withFileTypes: true }));
+    if (entriesResult.isError()) {
+        return [];
+    }
+    const entries = entriesResult.value;
+    const files = entries.filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".md"));
+    const result = [];
+    for (const file of files) {
+        const fullPath = path.join(dirPath, file.name);
+        result.push({ path: fullPath, lineCount: await fileLineCount(fullPath) });
+    }
+    return result.sort((a, b) => a.path.localeCompare(b.path));
+}
+export async function discoverGovernanceArtifacts(governanceDir) {
+    const result = [];
+    for (const artifact of FILE_ARTIFACTS) {
+        const artifactPath = path.join(governanceDir, artifact);
+        const accessResult = await catchIt(fs.access(artifactPath));
+        if (!accessResult.isError()) {
+            result.push({
+                name: artifact,
+                kind: "file",
+                path: artifactPath,
+                exists: true,
+                lineCount: await fileLineCount(artifactPath),
+            });
+        }
+        else {
+            result.push({ name: artifact, kind: "file", path: artifactPath, exists: false });
+        }
+    }
+    for (const artifact of DIRECTORY_ARTIFACTS) {
+        const artifactPath = path.join(governanceDir, artifact);
+        const accessResult = await catchIt(fs.access(artifactPath));
+        if (!accessResult.isError()) {
+            result.push({
+                name: artifact,
+                kind: "directory",
+                path: artifactPath,
+                exists: true,
+                markdownFiles: await listMarkdownFiles(artifactPath),
+            });
+        }
+        else {
+            result.push({ name: artifact, kind: "directory", path: artifactPath, exists: false, markdownFiles: [] });
+        }
+    }
+    return result;
+}

package/output/helpers/files/files.test.js

@@ -0,0 +1,32 @@
+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";
+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("files module", () => {
+    it("discovers governance artifacts with paths and line counts", async () => {
+        const root = await createTempDir();
+        await fs.writeFile(path.join(root, "README.md"), "# Readme\n", "utf-8");
+        await fs.writeFile(path.join(root, "tasks.md"), "# Tasks\n## TODO\n", "utf-8");
+        await fs.mkdir(path.join(root, "designs"), { recursive: true });
+        await fs.writeFile(path.join(root, "designs", "feature-design.md"), "# Design\n", "utf-8");
+        const artifacts = await discoverGovernanceArtifacts(root);
+        const readme = artifacts.find((item) => item.name === "README.md");
+        const designs = artifacts.find((item) => item.name === "designs");
+        expect(readme?.exists).toBe(true);
+        expect(readme?.lineCount).toBe(2);
+        expect(designs?.exists).toBe(true);
+        expect(designs?.markdownFiles?.[0].path.endsWith("feature-design.md")).toBe(true);
+    });
+});

package/output/helpers/files/index.js

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

package/output/helpers/index.js

@@ -0,0 +1,3 @@
+export * from './catch/index.js';
+export * from './files/index.js';
+export * from './markdown/index.js';

package/output/helpers/markdown/index.js

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

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

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { catchIt } from "./helpers/catch/index.js";
+const GLOBAL_EVENT_FILES = {
+    onAssigned: "on_task_assigned.md",
+    onCompleted: "on_task_completed.md",
+    onBlocked: "on_task_blocked.md",
+    onReopened: "on_task_reopened.md",
+};
+export function detectHookEvent(from, to) {
+    if (to === "IN_PROGRESS") {
+        return from === "DONE" ? "onReopened" : "onAssigned";
+    }
+    if (to === "DONE") {
+        return "onCompleted";
+    }
+    if (to === "BLOCKED") {
+        return "onBlocked";
+    }
+    return null;
+}
+async function readHookFile(filePath) {
+    const contentResult = await catchIt(fs.readFile(filePath, "utf-8"));
+    if (contentResult.isError()) {
+        return { ok: false, warning: `Hook file not found or unreadable: ${filePath}` };
+    }
+    const content = contentResult.value;
+    if (content.trim().length === 0) {
+        return { ok: true, content: "" };
+    }
+    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,
+            };
+        }
+    }
+    const globalPath = path.join(governanceDir, "hooks", GLOBAL_EVENT_FILES[event]);
+    const globalFile = await readHookFile(globalPath);
+    if (globalFile.ok) {
+        return {
+            event,
+            source: "global",
+            path: globalPath,
+            content: globalFile.content,
+        };
+    }
+    return {
+        event,
+        source: "none",
+        warning: globalFile.warning,
+    };
+}