# project-mcp
> **Intent-based MCP server for project documentation** — Maps natural language
> to the right sources automatically
[](https://www.npmjs.com/package/project-mcp)
[](https://nodejs.org/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
When users say "project", "docs", or "todos", `project-mcp` automatically
searches the right directories—no configuration needed. It understands intent,
not just directory names.
---
# ⚡ Quick Start
## Install
```bash
npm install project-mcp
```
## Configure
Add to `.mcp.json`:
```json
{
"mcpServers": {
"project": {
"command": "npx",
"args": ["-y", "project-mcp"]
}
}
}
```
**That's it.** The server automatically finds and indexes:
- `.project/` — Operational truth (plans, todos, status)
- Root markdown files — README.md, DEVELOPMENT.md, etc.
- `docs/` — Reference documentation
---
## Table of Contents
- [project-mcp](#project-mcp)
- [⚡ Quick Start](#-quick-start)
- [Install](#install)
- [Configure](#configure)
- [Table of Contents](#table-of-contents)
- [🎯 Why project-mcp?](#-why-project-mcp)
- [🛠️ Available Tools (37)](#️-available-tools-37)
- [Search Tools](#search-tools)
- [Project Management Tools](#project-management-tools)
- [Backlog Tools](#backlog-tools)
- [Task Management Tools](#task-management-tools)
- [Archive Tools](#archive-tools)
- [Decision \& Status Tools](#decision--status-tools)
- [Quality Tools](#quality-tools)
- [📋 Task Management System](#-task-management-system)
- [Workflow](#workflow)
- [Task File Format (Active Tasks)](#task-file-format-active-tasks)
- [Agent Execution Loop](#agent-execution-loop)
- [Key Features](#key-features)
- [🏗️ Project Structure Guide](#️-project-structure-guide)
- [Recommended Directory Structure](#recommended-directory-structure)
- [What Goes Where?](#what-goes-where)
- [`.project/` — Operational Truth](#project--operational-truth)
- [`docs/` — Reference Truth](#docs--reference-truth)
- [🎨 Intent Mapping](#-intent-mapping)
- [How It Works](#how-it-works)
- [📝 Documentation Examples](#-documentation-examples)
- [Example: `.project/index.md` (Contract File)](#example-projectindexmd-contract-file)
- [Example: Task Creation](#example-task-creation)
- [Example: Getting Next Task](#example-getting-next-task)
- [Example: Initialize Project](#example-initialize-project)
- [Example: Import Tasks to Backlog](#example-import-tasks-to-backlog)
- [Example: Promote Task to Active Work](#example-promote-task-to-active-work)
- [Example: Archive Completed Task](#example-archive-completed-task)
- [⚙️ Configuration](#️-configuration)
- [Custom Documentation Directory](#custom-documentation-directory)
- [Custom Working Directory](#custom-working-directory)
- [🧪 Development](#-development)
- [📚 Documentation](#-documentation)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
---
## 🎯 Why project-mcp?
**The Problem:** AI agents need to search project documentation, but:
- Users say "project" not ".project/"
- Different queries need different sources
- Manual source mapping is error-prone
- No standard way to organize project knowledge
**The Solution:** Intent-based search that maps language to sources
automatically:
| User Says | Searches |
| --------------------------------------- | ---------------------------------- |
| "project" / "the project" | `.project/` + root files + `docs/` |
| "docs" / "documentation" | Only `docs/` |
| "plan" / "todos" / "roadmap" / "status" | Only `.project/` |
---
## 🛠️ Available Tools (37)
### Search Tools
| Tool | Description | Use When |
| ------------------- | -------------------------------------- | ---------------------------------------------- |
| `search_project` | Intent-based search across all sources | User says "project" or asks about status/plans |
| `search_docs` | Search reference documentation only | User specifically asks for "docs" |
| `get_doc` | Get full file content | You know the exact file path |
| `list_docs` | List all documentation files | Browsing available docs |
| `get_doc_structure` | Get directory structure | Understanding organization |
### Project Management Tools
| Tool | Description | Use When |
| ---------------------------- | ---------------------------------------------- | -------------------------------- |
| `init_project` | Initialize `.project/` with all standard files | Starting a new project |
| `manage_project_file` | Smart create/update based on content analysis | Auto-detect which file to update |
| `create_or_update_roadmap` | Create or update ROADMAP.md | Planning milestones and phases |
| `create_or_update_todo` | Create or update TODO.md | Managing project-wide todos |
| `create_or_update_status` | Create or update STATUS.md | Tracking project health |
| `create_or_update_index` | Create or update index.md (contract file) | Defining source mappings |
| `create_or_update_decisions` | Create or update DECISIONS.md | Recording architecture decisions |
| `check_project_state` | Check which project files exist | Before making changes |
### Backlog Tools
| Tool | Description | Use When |
| --------------------- | ---------------------------------------------------- | ------------------------------- |
| `add_to_backlog` | Add single item to BACKLOG.md | Quick task creation |
| `get_backlog` | Read backlog with filtering/sorting | Viewing queued work |
| `update_backlog_item` | Update priority, title, tags, phase | Adjusting backlog items |
| `remove_from_backlog` | Delete item without promoting | Removing cancelled work |
| `import_tasks` | Parse plan/roadmap and bulk add to BACKLOG.md | Populating from roadmap |
| `promote_task` | Move task from BACKLOG to active work (creates YAML) | Starting work on a backlog item |
### Task Management Tools
| Tool | Description | Use When |
| ----------------- | --------------------------------------------- | ------------------------ |
| `create_task` | Create active task directly (bypass backlog) | Urgent/immediate work |
| `get_task` | Read specific task by ID with full details | Viewing task details |
| `update_task` | Update any task field, transition status | Modifying existing tasks |
| `delete_task` | Permanently remove a task (with confirmation) | Removing cancelled tasks |
| `search_tasks` | Search tasks by keyword in title/content | Finding specific tasks |
| `get_next_task` | Get dependency-aware next task(s) to work on | Determining what to do |
| `list_tasks` | List/filter tasks with summary dashboard | Reviewing all tasks |
| `sync_todo_index` | Generate TODO.md dashboard from active tasks | Updating the overview |
### Archive Tools
| Tool | Description | Use When |
| --------------------- | ------------------------------------ | --------------------------- |
| `archive_task` | Move completed task to archive/ | Cleaning up done work |
| `list_archived_tasks` | List tasks in archive with filtering | Reviewing completed history |
| `unarchive_task` | Restore task from archive to active | Reopening completed work |
### Decision & Status Tools
| Tool | Description | Use When |
| ----------------------- | --------------------------------- | -------------------------------- |
| `add_decision` | Record ADR with structured format | Documenting architecture choices |
| `get_decision` | Read specific decision by ADR ID | Viewing decision details |
| `list_decisions` | List/filter architecture ADRs | Reviewing past decisions |
| `update_project_status` | Quick timestamped status update | Reporting progress |
| `add_roadmap_milestone` | Add milestone with deliverables | Planning future work |
| `get_roadmap` | Read roadmap content | Viewing planned work |
### Quality Tools
| Tool | Description | Use When |
| ------------------- | ---------------------------------------- | -------------------------------- |
| `lint_project_docs` | Validate documentation against standards | Before commits, ensuring quality |
---
## 📋 Task Management System
Tasks flow from **planning → backlog → active → archive**. Only active tasks
(10-30 items) are YAML files.
### Workflow
```
ROADMAP.md ──→ import_tasks ──→ BACKLOG.md ──→ promote_task ──→ todos/*.md ──→ archive_task ──→ archive/
(plan) (extract) (queue) (activate) (work) (complete) (history)
hundreds ok hundreds ok 10-30 files YAML files
```
| Stage | Files | Purpose |
| -------- | -------------- | ------------------------------------------ |
| Planning | `ROADMAP.md` | Phases, milestones, high-level |
| Backlog | `BACKLOG.md` | Prioritized queue, hundreds of items OK |
| Active | `todos/*.md` | YAML files with full metadata, 10-30 items |
| Archive | `archive/*.md` | Completed work history |
### Task File Format (Active Tasks)
```yaml
---
id: AUTH-001
title: Implement OAuth authentication
project: AUTH
priority: P0
status: todo
owner: cursor
depends_on:
- AUTH-002
blocked_by: []
tags:
- security
- feature
estimate: 2d
due: 2025-01-15
created: 2025-12-29
updated: 2025-12-29
---
# AUTH-001: Implement OAuth authentication
## Description
Implement OAuth 2.0 authentication flow...
## Subtasks
- [ ] Set up OAuth provider
- [ ] Implement callback handler
- [x] Configure environment variables
## Notes
```
### Agent Execution Loop
```
┌─────────────────────────────────────────────────────────────┐
│ 1. promote_task(task_id: "AUTH-001") │
│ → Creates todos/AUTH-001.md from BACKLOG.md │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. get_next_task() │
│ → Returns AUTH-001 (dependencies met, highest priority) │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. update_task(id: "AUTH-001", status: "in_progress") │
│ → Agent works on the task │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. update_task(id: "AUTH-001", status: "done") │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 5. archive_task(task_id: "AUTH-001") │
│ → Moves to archive/, keeps todos/ small │
└─────────────────────────────────────────────────────────────┘
```
### Key Features
- **Backlog-first**: Plan hundreds of items in `BACKLOG.md`, promote to active
as needed
- **Small active queue**: Only 10-30 YAML task files at a time, not hundreds
- **Stable IDs**: `{PROJECT}-{NNN}` format (e.g., `AUTH-001`, `API-042`)
- **Dependencies**: `depends_on` array - task won't appear in `get_next_task`
until deps are done
- **Priority Sorting**: P0 (critical) → P3 (low) in all views
- **Status Workflow**: `todo` → `in_progress` → `blocked` | `review` → `done`
- **Archive history**: Completed work preserved in `archive/` for reference
---
## 🏗️ Project Structure Guide
### Recommended Directory Structure
```
my-project/
├── .project/ # Operational truth (current state)
│ ├── index.md # Contract file (defines source mappings)
│ ├── BACKLOG.md # Prioritized work queue (hundreds of items OK)
│ ├── TODO.md # Task dashboard (auto-generated)
│ ├── ROADMAP.md # Project roadmap and milestones
│ ├── STATUS.md # Current project status
│ ├── DECISIONS.md # Architecture and design decisions
│ ├── todos/ # Active tasks (10-30 YAML files)
│ │ ├── AUTH-001.md
│ │ └── AUTH-002.md
│ └── archive/ # Completed tasks (history)
│ └── AUTH-000.md
│
├── docs/ # Reference truth (long-form docs)
│ ├── README.md
│ ├── architecture/
│ └── guides/
│
├── README.md # Project overview
└── CONTRIBUTING.md # Contribution guidelines
```
### What Goes Where?
#### `.project/` — Operational Truth
**Purpose:** Current state, plans, decisions, and active work.
| File | Purpose |
| -------------- | ---------------------------------------------------- |
| `index.md` | Contract file (defines how agents interpret sources) |
| `BACKLOG.md` | Prioritized work queue (future tasks, hundreds OK) |
| `TODO.md` | Task dashboard (auto-generated by `sync_todo_index`) |
| `ROADMAP.md` | Future plans, milestones, upcoming features |
| `STATUS.md` | Current project status, recent changes, health |
| `DECISIONS.md` | Architecture decisions, trade-offs, rationale |
| `todos/` | Active task files (10-30 items, YAML frontmatter) |
| `archive/` | Completed tasks (history, reference) |
#### `docs/` — Reference Truth
**Purpose:** Long-form documentation, guides, and reference materials.
- Architecture documentation
- API references
- How-to guides
- Technical specifications
---
## 🎨 Intent Mapping
The server uses intent detection to route queries to the right sources:
```
User Query
│
├─ "project" / "the project"
│ └─→ Searches: .project/ + root files + docs/
│
├─ "docs" / "documentation"
│ └─→ Searches: docs/ only
│
├─ "plan" / "todos" / "roadmap" / "status"
│ └─→ Searches: .project/ only
│
└─ Default
└─→ Searches: All sources
```
### How It Works
1. User query: "What's the project status?"
2. Intent detection: Keywords "status" → intent `plan`
3. Source mapping: `plan` → searches only `.project/`
4. Results: Returns `.project/STATUS.md`, `.project/TODO.md`, etc.
---
## 📝 Documentation Examples
### Example: `.project/index.md` (Contract File)
```markdown
# 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
```
### Example: Task Creation
```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"]
}
}
```
### Example: Getting Next Task
```json
{
"tool": "get_next_task",
"arguments": {
"owner": "cursor",
"limit": 3
}
}
```
Returns tasks sorted by priority where all dependencies are complete.
### Example: Initialize Project
```json
{
"tool": "init_project",
"arguments": {
"project_name": "My App",
"project_description": "A web application for task management"
}
}
```
Creates `.project/` with all standard files: `index.md`, `TODO.md`,
`ROADMAP.md`, `STATUS.md`, `DECISIONS.md`, and `todos/` directory.
### Example: Import Tasks to Backlog
```json
{
"tool": "import_tasks",
"arguments": {
"source": ".project/ROADMAP.md",
"project": "APP",
"dry_run": true
}
}
```
Parses the roadmap and adds tasks to `BACKLOG.md`. Use `dry_run: true` to
preview first.
### Example: Promote Task to Active Work
```json
{
"tool": "promote_task",
"arguments": {
"task_id": "APP-001",
"owner": "cursor",
"estimate": "2h"
}
}
```
Moves task from `BACKLOG.md` to `todos/APP-001.md` with full YAML frontmatter.
### Example: Archive Completed Task
```json
{
"tool": "archive_task",
"arguments": {
"task_id": "APP-001"
}
}
```
Moves completed task from `todos/` to `archive/` to keep active queue small.
---
## ⚙️ Configuration
### Custom Documentation Directory
```json
{
"mcpServers": {
"project": {
"command": "npx",
"args": ["-y", "project-mcp"],
"env": {
"DOCS_DIR": "/path/to/documentation"
}
}
}
}
```
### Custom Working Directory
```json
{
"mcpServers": {
"project": {
"command": "npx",
"args": ["-y", "project-mcp"],
"cwd": "/path/to/project/root"
}
}
}
```
---
## 🧪 Development
```bash
# Clone repository
git clone https://github.com/pouyanafisi/project-mcp.git
cd project-mcp
# Install dependencies
npm install
# Run tests
npm test
# Test the server
node src/index.js
```
---
## 📚 Documentation
- **[Examples](EXAMPLES.md)** — Usage examples and patterns
- **[Contributing](CONTRIBUTING.md)** — How to contribute
- **[Security](SECURITY.md)** — Security policy
- **[Changelog](CHANGELOG.md)** — Version history
- **[Release Notes v2.0.0](docs/releases/RELEASE_NOTES_v2.0.0.md)** — Latest
release
---
## 🤝 Contributing
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
[Get Started](#-quick-start) • [Documentation](#-documentation) •
[Examples](EXAMPLES.md) •
[Report Issue](https://github.com/pouyanafisi/project-mcp/issues)
