Project Knowledge Index

Contract for AI Agents

When a user says "project", the canonical sources of truth are:

1. .project/ — Current state, plans, todos, decisions
2. Root markdown files — README.md, DEVELOPMENT.md, etc.
3. docs/ — Long-form reference documentation

Principles

• Natural language stays natural - Users say "project" not ".project/"
• Agents don't guess - Explicit mappings defined here
• Intent over structure - Language maps to intent, not directory names

#### 示例：任務創建
```json
{
    "tool": "create_task",
    "arguments": {
        "title": "Implement OAuth authentication",
        "project": "AUTH",
        "priority": "P0",
        "owner": "cursor",
        "description": "Add OAuth 2.0 support for Google and GitHub",
        "depends_on": ["AUTH-002"],
        "estimate": "2d",
        "tags": ["security", "feature"]
    }
}

示例：獲取下一個任務

{
    "tool": "get_next_task",
    "arguments": {
        "owner": "cursor",
        "limit": 3
    }
}

返回按優先級排序且所有依賴項都已完成的任務。

示例：初始化項目

{
    "tool": "init_project",
    "arguments": {
        "project_name": "My App",
        "project_description": "A web application for task management"
    }
}

創建包含所有標準文件的 .project/：index.md、TODO.md、ROADMAP.md、STATUS.md、DECISIONS.md 和 todos/ 目錄。

示例：導入任務到待辦事項

{
    "tool": "import_tasks",
    "arguments": {
        "source": ".project/ROADMAP.md",
        "project": "APP",
        "dry_run": true
    }
}

解析路線圖並將任務添加到 BACKLOG.md。使用 dry_run: true 先進行預覽。

示例：將任務提升到活躍工作

{
    "tool": "promote_task",
    "arguments": {
        "task_id": "APP-001",
        "owner": "cursor",
        "estimate": "2h"
    }
}

將任務從 BACKLOG.md 移動到 todos/APP-001.md，並帶有完整的 YAML 前置元數據。

示例：存檔已完成的任務

{
    "tool": "archive_task",
    "arguments": {
        "task_id": "APP-001"
    }
}

將已完成的任務從 todos/ 移動到 archive/，以保持活躍隊列的精簡。

⚙️ 配置

自定義文檔目錄

{
    "mcpServers": {
        "project": {
            "command": "npx",
            "args": ["-y", "project-mcp"],
            "env": {
                "DOCS_DIR": "/path/to/documentation"
            }
        }
    }
}

自定義工作目錄

{
    "mcpServers": {
        "project": {
            "command": "npx",
            "args": ["-y", "project-mcp"],
            "cwd": "/path/to/project/root"
        }
    }
}

🧪 開發

# 克隆倉庫
git clone https://github.com/pouyanafisi/project-mcp.git
cd project-mcp

# 安裝依賴
npm install

# 運行測試
npm test

# 測試服務器
node src/index.js