article

README

Project Knowledge Index

Contract for AI Agents

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

.project/ — Current state, plans, todos, decisions
Root markdown files — README.md, DEVELOPMENT.md, etc.
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

project-mcp