@projitive/mcp 1.0.0-beta.5 → 1.0.1

package/README.md

@@ -1,36 +1,150 @@
 # @projitive/mcp
 
-**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.0**
+Language: English | [简体中文](README_CN.md)
 
-Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现项目、发现任务、定位证据，并按治理流程推进。
+**Current Spec Version: projitive-spec v1.0.0 | MCP Version: 1.0.1**
 
-## 规范版本
+Projitive MCP server (semantic interface edition) helps agents discover projects, select tasks, locate evidence, and execute under governance workflows.
 
-- 当前遵循规范版本：`projitive-spec v1.0.0`
-- 说明：Projitive 是通用治理规范，MCP 只是该规范的一种工具实现。
-- 对齐规则：MCP 的主版本必须与规范主版本一致（当前均为 `v1.x`）
+## Agent Delivery Loop
 
-## 设计边界
+```mermaid
+flowchart LR
+  A[taskNext / projectNext] --> B[taskContext / projectContext]
+  B --> C[Update tasks/designs/reports]
+  C --> D[taskContext verify]
+  D --> E{More actionable work?}
+  E -->|Yes| A
+  E -->|No| F[Done / wait for new tasks]
+```
+
+## Why Developers Choose This MCP
+
+- Predictable API family: `List/Context` as core, `Next/Scan/Locate` for acceleration.
+- Governance-safe automation: state changes are guided by evidence-first workflow.
+- Agent-ready outputs: markdown contracts optimized for tool-chaining, not raw JSON blobs.
+- Production publishing pipeline: release-triggered CI with lint/test/publish gates.
+
+## How It Helps Agents Manage and Advance Projects
+
+This MCP is designed to make agent execution operational, not just informative. It gives agents a closed-loop workflow:
+
+1. **Find what to do next**
+  - `taskNext` or `projectNext` ranks actionable targets.
+2. **Build the right context**
+  - `taskContext` / `projectContext` / `roadmapContext` provide evidence, references, and next-call hints.
+3. **Execute with governance constraints**
+  - Agent updates markdown artifacts (`tasks.md`, `designs/`, `reports/`) with immutable IDs and evidence rules.
+4. **Re-verify and continue**
+  - Re-run `taskContext` (or `roadmapContext`) to confirm consistency, then move to the next task.
+
+In short: it converts agent work from ad-hoc edits into a **discover → decide → execute → verify** delivery loop.
+
+## Agent Workflow (Shortest Path)
+
+```text
+taskNext
+  -> taskContext
+  -> update artifacts (tasks/designs/reports)
+  -> taskContext (verify)
+  -> taskNext (next cycle)
+```
+
+When the agent starts inside a project:
+
+```text
+projectLocate -> projectContext -> taskList -> taskContext
+```
+
+## Quick Start
+
+```bash
+cd packages/mcp
+npm ci
+npm run build
+npm run test
+```
+
+Then configure your MCP client to run:
+
+```bash
+node /absolute/path/to/packages/mcp/output/index.js
+```
+
+## Spec Version
+
+- Current aligned spec version: `projitive-spec v1.0.0`
+- Note: Projitive is a general governance specification; MCP is one implementation of this spec.
+- Alignment rule: MCP major version must match the spec major version (currently both `v1.x`).
+
+## Design Boundaries
+
+- MCP handles discovery, locating, summarization, and execution guidance.
+- Agents/AI handle reading and updating markdown content.
+- MCP does not provide direct artifact-write APIs such as `task.update_*`, `roadmap.update_*`, or `sync_*`.
+- All tool outputs are agent-oriented Markdown (not raw JSON objects).
+- Standard output sections: `Summary` / `Evidence` / `Agent Guidance` / `Next Call`.
+- Standard error sections: `Error` / `Next Step` / `Retry Example`.
+
+## MCP Capability Model
+
+- Tools: execute discovery/locating/summarization actions (primary channel).
+- Resources: expose readable governance artifacts for low-cost context loading.
+- Prompts: provide parameterized workflow templates to reduce execution drift.
+
+### Resources (Implemented)
 
-- MCP 负责：发现、定位、汇总、推进指导。
-- AI 负责：读取与更新 Markdown 正文内容。
-- MCP 不提供：`task.update_*`、`roadmap.update_*`、`sync_*` 这类直接写入治理工件的方法。
-- 所有工具返回内容：面向 Agent 的 Markdown（不是 JSON 对象）。
-- 输出结构统一为：`Summary` / `Evidence` / `Agent Guidance`。
-- 错误结构统一为：`Error` / `Next Step`。
+- `projitive://governance/workspace`: reads `.projitive/README.md`
+- `projitive://governance/tasks`: reads `.projitive/tasks.md`
+- `projitive://governance/roadmap`: reads `.projitive/roadmap.md`
+- `projitive://mcp/method-catalog`: method naming and role catalog (`List/Context/Next/Scan/Locate`)
+
+### Prompts (Implemented)
+
+- `executeTaskWorkflow`: standard execution chain (`taskNext -> taskContext -> artifacts update -> verify`)
+- `updateTaskStatusWithEvidence`: status transition + evidence alignment template
+- `triageProjectGovernance`: project-level governance triage template
 
 ## Tools Methods
 
-### 发现层
+### Discovery Layer
 
-#### `project.next`
+#### `projectInit`
 
-- **作用**：直接拉取最近可推进的项目（按可执行任务数和最近更新时间排序）。
-- **输入**：`rootPath?`、`maxDepth?`、`limit?`
-- **输出示例（Markdown）**：
+- **Purpose**: manually initialize governance directory structure for a project (default `.projitive`).
+- **Input**: `rootPath?`, `governanceDir?`, `force?`
+- **Output Example (Markdown)**:
 
 ```markdown
-# project.next
+# projectInit
+
+## Summary
+- rootPath: /workspace/proj-a
+- governanceDir: /workspace/proj-a/.projitive
+- markerPath: /workspace/proj-a/.projitive/.projitive
+- force: false
+
+## Evidence
+- createdFiles: 4
+- updatedFiles: 0
+- skippedFiles: 0
+
+## Agent Guidance
+- If files were skipped and you want to overwrite templates, rerun with force=true.
+- Continue with projectContext and taskList for execution.
+
+## Next Call
+- projectContext(projectPath="/workspace/proj-a/.projitive")
+```
+
+#### `projectNext`
+
+- **Purpose**: directly list recently actionable projects (ranked by actionable task count and recency).
+- **Input**: `rootPath?`, `maxDepth?`, `limit?`
+- **Output Example (Markdown)**:
+
+```markdown
+# projectNext
 
 ## Summary
 - rootPath: /workspace
@@ -45,18 +159,21 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 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.
+- Pick top 1 project and call `projectContext` with its governanceDir.
+- Then call `taskList` and `taskContext` to continue execution.
+
+## Next Call
+- projectContext(projectPath="/workspace/proj-a")
 ```
 
-#### `project.scan`
+#### `projectScan`
 
-- **作用**：扫描目录并发现可治理项目。
-- **输入**：`rootPath?`、`maxDepth?`
-- **输出示例（Markdown）**：
+- **Purpose**: scan directories and discover governable projects.
+- **Input**: `rootPath?`, `maxDepth?`
+- **Output Example (Markdown)**:
 
 ```markdown
-# project.scan
+# projectScan
 
 ## Summary
 - rootPath: /workspace
@@ -69,18 +186,21 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 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.
+- Use one discovered project path and call `projectLocate` to lock governance root.
+- Then call `projectContext` to inspect current governance state.
+
+## Next Call
+- projectLocate(inputPath="/workspace/proj-a")
 ```
 
-#### `project.locate`
+#### `projectLocate`
 
-- **作用**：当 Agent 已经在某个项目目录内时，向上定位最近 `.projitive`，确定当前项目治理根目录。
-- **输入**：`inputPath`
-- **输出示例（Markdown）**：
+- **Purpose**: when an agent is already inside a project path, resolve the nearest `.projitive` upward.
+- **Input**: `inputPath`
+- **Output Example (Markdown)**:
 
 ```markdown
-# project.locate
+# projectLocate
 
 ## Summary
 - resolvedFrom: /workspace/proj-a/packages/mcp
@@ -88,17 +208,20 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 - markerPath: /workspace/proj-a/.projitive
 
 ## Agent Guidance
-- Next: call `project.overview` with this governanceDir to get task and roadmap summaries.
+- Call `projectContext` with this governanceDir to get task and roadmap summaries.
+
+## Next Call
+- projectContext(projectPath="/workspace/proj-a")
 ```
 
-#### `project.overview`
+#### `projectContext`
 
-- **作用**：自动汇总治理状态，而不是只返回文件列表。
-- **输入**：`projectPath`
-- **输出示例（Markdown）**：
+- **Purpose**: summarize governance state instead of only returning file lists.
+- **Input**: `projectPath`
+- **Output Example (Markdown)**:
 
 ```markdown
-# project.overview
+# projectContext
 
 ## Summary
 - governanceDir: /workspace/proj-a
@@ -122,20 +245,23 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 - ✅ 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.
+- Start from `taskList` to choose a target task.
+- Then call `taskContext` with a task ID to retrieve evidence locations and reading order.
+
+## Next Call
+- taskList(projectPath="/workspace/proj-a")
 ```
 
-### 任务层
+### Task Layer
 
-#### `task.next`
+#### `taskNext`
 
-- **作用**：一步完成“发现项目 + 选择最可推进任务 + 返回证据定位与阅读顺序”，用于 Agent 直接开工。
-- **输入**：`rootPath?`、`maxDepth?`、`topCandidates?`
-- **输出示例（Markdown）**：
+- **Purpose**: one-step workflow for project discovery + best task selection + evidence/read-order output.
+- **Input**: `rootPath?`, `maxDepth?`, `topCandidates?`
+- **Output Example (Markdown)**:
 
 ```markdown
-# task.next
+# taskNext
 
 ## Summary
 - rootPath: /workspace
@@ -156,6 +282,10 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 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
 
+### Selection Reason
+- Rank rule: projectScore DESC -> taskPriority DESC -> taskUpdatedAt DESC.
+- Selected candidate scores: projectScore=6, taskPriority=2, taskUpdatedAtMs=1739793600000.
+
 ### Suggested Read Order
 1. /workspace/proj-a/tasks.md
 2. /workspace/proj-a/designs/mcp-design.md
@@ -163,19 +293,22 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 
 ## 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.
+- Re-run `taskContext` for the selectedTaskId after edits to verify evidence consistency.
+
+## Next Call
+- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
 ```
 
-- **推荐路径**：优先调用 `task.next`，避免 `project.next -> project.overview -> task.list -> task.get` 的多跳链路。
+- **Recommended Path**: prefer `taskNext` to avoid multi-hop flow (`projectNext -> projectContext -> taskList -> taskContext`).
 
-#### `task.list`
+#### `taskList`
 
-- **作用**：返回当前项目任务清单，支持按状态过滤与排序。
-- **输入**：`projectPath`、`status?`、`limit?`
-- **输出示例（Markdown）**：
+- **Purpose**: list tasks in current project, with optional status filtering and limiting.
+- **Input**: `projectPath`, `status?`, `limit?`
+- **Output Example (Markdown)**:
 
 ```markdown
-# task.list
+# taskList
 
 ## Summary
 - governanceDir: /workspace/proj-a
@@ -189,25 +322,28 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 - 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`.
+- Pick one task ID and call `taskContext`.
+
+## Next Call
+- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
 ```
 
-#### `task.get`
+#### `taskContext`
 
-- **作用**：基于任务 ID 一次性返回任务详情 + 关联证据位置（替代 `trace.references`）。
-- **输入**：`projectPath`、`taskId`
-- **HOOKS 注入**：
-  - 若存在 `hooks/task_get_head.md`，其内容会自动追加到返回结果最前面。
-  - 若存在 `hooks/task_get_footer.md`，其内容会自动追加到返回结果最后面。
-  - 用于给 Agent 注入项目级自定义提示，不改变 task.get 核心结构。
-- **输出示例（Markdown）**：
+- **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 内容（如果存在）]
+[hooks/task_get_head.md content (if present)]
 
 ---
 
-# task.get
+# taskContext
 
 ## Summary
 - governanceDir: /workspace/proj-a
@@ -238,22 +374,27 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 ## Agent Guidance
 - Read the files in Suggested Read Order.
 - Verify whether current status and evidence are consistent.
+- This task is IN_PROGRESS: prioritize finishing with report/design evidence updates.
+- Verify references stay consistent before marking DONE.
+
+## Next Call
+- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0003")
 
 ---
 
-[hooks/task_get_footer.md 内容（如果存在）]
+[hooks/task_get_footer.md content (if present)]
 ```
 
-### 路线层
+### Roadmap Layer
 
-#### `roadmap.list`
+#### `roadmapList`
 
-- **作用**：列出路线图项目及其关联任务概览。
-- **输入**：`projectPath`
-- **输出示例（Markdown）**：
+- **Purpose**: list roadmap items and linked task summary.
+- **Input**: `projectPath`
+- **Output Example (Markdown)**:
 
 ```markdown
-# roadmap.list
+# roadmapList
 
 ## Summary
 - governanceDir: /workspace/proj-a
@@ -265,17 +406,20 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 - ROADMAP-0002 | linkedTasks=3
 
 ## Agent Guidance
-- Next: call `roadmap.get` with a roadmap ID to inspect references and related tasks.
+- Pick one roadmap ID and call `roadmapContext`.
+
+## Next Call
+- roadmapContext(projectPath="/workspace/proj-a", roadmapId="ROADMAP-0001")
 ```
 
-#### `roadmap.get`
+#### `roadmapContext`
 
-- **作用**：获取单个路线图详情与证据定位信息。
-- **输入**：`projectPath`、`roadmapId`
-- **输出示例（Markdown）**：
+- **Purpose**: get single roadmap detail and reference locations.
+- **Input**: `projectPath`, `roadmapId`
+- **Output Example (Markdown)**:
 
 ```markdown
-# roadmap.get
+# roadmapContext
 
 ## Summary
 - governanceDir: /workspace/proj-a
@@ -295,12 +439,15 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 ## Agent Guidance
 - Read roadmap references first, then related tasks.
 - Keep ROADMAP/TASK IDs unchanged while updating markdown files.
+
+## Next Call
+- roadmapContext(projectPath="/workspace/proj-a", roadmapId="ROADMAP-0001")
 ```
 
-## 统一错误输出示例
+## Unified Error Output Example
 
 ```markdown
-# task.get
+# taskContext
 
 ## Error
 - cause: Invalid task ID format: TASK-12
@@ -308,11 +455,14 @@ Projitive MCP server（语义化接口设计版），用于帮助 Agent 发现
 ## Next Step
 - expected format: TASK-0001
 - retry with a valid task ID
+
+## Retry Example
+- taskContext(projectPath="/workspace/proj-a", taskId="TASK-0001")
 ```
 
-## Agent 推荐调用流程
+## Recommended Agent Call Flow
 
-1. `task.next`：一步发现并选择最可推进任务，直接开工（默认路径）。
-2. `task.get`：在需要更完整上下文时，按 taskId 拉取详细证据。
-3. `project.next`：仅在需要“先选项目、再选任务”的项目级调度场景使用（可选）。
-4. 当 Agent 已在项目内时，用 `project.locate` 快速定位当前项目治理根目录。
+1. `taskNext`: one-step discovery and top task selection (default path).
+2. `taskContext`: fetch detailed evidence for a specific task ID when needed.
+3. `projectNext`: optional project-level scheduling flow when you need project-first dispatch.
+4. When already in a project path, use `projectLocate` to quickly resolve governance root.