Which integrations are available for this server?

Mentioned as an example OAuth provider in task creation documentation, indicating potential OAuth authentication integration capabilities. Mentioned as an example OAuth provider in task creation documentation, indicating potential OAuth authentication integration capabilities. Provides tools for managing and searching Markdown-based project documentation, including files like README.md, ROADMAP.md, TODO.md, and STATUS.md across .project/ and docs/ directories. Provides tools for managing task files with YAML frontmatter, including creating, updating, and archiving tasks with structured metadata for project management workflows.

How do I use Project MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Project MCP what's the next task in the backlog?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

project-mcp

Intent-based MCP server for project documentation — Maps natural language to the right sources automatically

npm version Node.js License: MIT MCP

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

npm install project-mcp

Configure

Add to .mcp.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

🎯 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)

---
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

User query: "What's the project status?"
Intent detection: Keywords "status" → intent plan
Source mapping: plan → searches only .project/
Results: Returns .project/STATUS.md, .project/TODO.md, etc.

📝 Documentation Examples

Example: `.project/index.md` (Contract File)

# 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

{
	"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

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

Returns tasks sorted by priority where all dependencies are complete.

Example: Initialize Project

{
	"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

{
	"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

{
	"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

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

Moves completed task from todos/ to archive/ to keep active queue small.

⚙️ Configuration

Custom Documentation Directory

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

Custom Working Directory

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

🧪 Development

# 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 — Usage examples and patterns
Contributing — How to contribute
Security — Security policy
Changelog — Version history
Release Notes v2.0.0 — Latest release

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE for details.

Get Started • Documentation • Examples • Report Issue