Project MCP
project-mcp is an intent-based MCP server for searching and managing project documentation, plans, and tasks.
Search project knowledge: Semantic search across
.project/,docs/, and root files, with intent mapping for “project”, “docs”, “plan”, “status”, “todos”, and more.Manage project files: Initialize
.project/structure and create/update ROADMAP, TODO, STATUS, index/contract, and DECISIONS files, including smart auto-detection of the right file.Task lifecycle: Create tasks with YAML metadata (ID, priority, status, owner, dependencies, estimates, tags), get dependency-aware next tasks, update/delete/search/list tasks, and sync the TODO dashboard.
Backlog management: Add/import/update/remove backlog items and promote them into active YAML task files.
Archive/reopen work: Archive completed tasks, list archived tasks, and unarchive them for further work.
Documentation authoring: Create/update docs, add release notes, update architecture docs, and list doc categories or the full doc structure.
Decisions & status: Add/list/get structured architecture decision records (ADRs) and post quick timestamped project status updates.
Roadmap planning: Add milestones with deliverables and read the roadmap.
Thought processing: Process brain-dump files into tasks, list/get thoughts, and archive processed thoughts with logging.
Quality checks: Lint project documentation for standards compliance, check project state, and auto-fix common issues.
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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
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-mcpRelated MCP server: Planer MCP Server
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
Table of Contents
🎯 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" |
|
"docs" / "documentation" | Only |
"plan" / "todos" / "roadmap" / "status" | Only |
🛠️ Available Tools (47)
Search Tools
Tool | Description | Use When |
| Intent-based search across all sources | User says "project" or asks about status/plans |
| Search reference documentation only | User specifically asks for "docs" |
| Get full file content | You know the exact file path |
| List all documentation files | Browsing available docs |
| Get directory structure | Understanding organization |
Project Management Tools
Tool | Description | Use When |
| Initialize | Starting a new project |
| Smart create/update based on content analysis | Auto-detect which file to update |
| Create or update ROADMAP.md | Planning milestones and phases |
| Create or update TODO.md | Managing project-wide todos |
| Create or update STATUS.md | Tracking project health |
| Create or update index.md (contract file) | Defining source mappings |
| Create or update DECISIONS.md | Recording architecture decisions |
| Check which project files exist | Before making changes |
Documentation Tools
Tool | Description | Use When |
| Create new doc in | Adding application documentation |
| Update existing doc in | Modifying reference docs |
| Add versioned release notes | Documenting releases |
| Create/update architecture docs | Documenting system design |
| List documentation categories | Understanding docs structure |
Backlog Tools
Tool | Description | Use When |
| Add single item to BACKLOG.md | Quick task creation |
| Read backlog with filtering/sorting | Viewing queued work |
| Update priority, title, tags, phase | Adjusting backlog items |
| Delete item without promoting | Removing cancelled work |
| Parse plan/roadmap and bulk add to BACKLOG.md | Populating from roadmap |
| Move task from BACKLOG to active work (creates YAML) | Starting work on a backlog item |
Task Management Tools
Tool | Description | Use When |
| Create active task directly (bypass backlog) | Urgent/immediate work |
| Read specific task by ID with full details | Viewing task details |
| Update any task field, transition status | Modifying existing tasks |
| Permanently remove a task (with confirmation) | Removing cancelled tasks |
| Search tasks by keyword in title/content | Finding specific tasks |
| Get dependency-aware next task(s) to work on | Determining what to do |
| List/filter tasks with summary dashboard | Reviewing all tasks |
| Generate TODO.md dashboard from active tasks | Updating the overview |
Archive Tools
Tool | Description | Use When |
| Move completed task to archive/ | Cleaning up done work |
| List tasks in archive with filtering | Reviewing completed history |
| Restore task from archive to active | Reopening completed work |
Decision & Status Tools
Tool | Description | Use When |
| Record ADR with structured format | Documenting architecture choices |
| Read specific decision by ADR ID | Viewing decision details |
| List/filter architecture ADRs | Reviewing past decisions |
| Quick timestamped status update | Reporting progress |
| Add milestone with deliverables | Planning future work |
| Read roadmap content | Viewing planned work |
Thoughts Tools
Tool | Description | Use When |
| Process brain dump files into tasks | Converting notes to actionable tasks |
| Archive processed thought files | Cleaning up processed notes |
| List unprocessed thought files | Reviewing pending brain dumps |
| List processed thought history | Reviewing what was processed |
| Read specific thought file | Viewing thought content |
Quality Tools
Tool | Description | Use When |
| 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 filesStage | Files | Purpose |
Planning |
| Phases, milestones, high-level |
Backlog |
| Prioritized queue, hundreds of items OK |
Active |
| YAML files with full metadata, 10-30 items |
Archive |
| 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
## NotesAgent 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 neededSmall 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_onarray - task won't appear inget_next_taskuntil deps are donePriority Sorting: P0 (critical) → P3 (low) in all views
Status Workflow:
todo→in_progress→blocked|review→doneArchive 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 guidelinesWhat Goes Where?
.project/ — Operational Truth
Purpose: Current state, plans, decisions, and active work.
File | Purpose |
| Contract file (defines how agents interpret sources) |
| Prioritized work queue (future tasks, hundreds OK) |
| Task dashboard (auto-generated by |
| Future plans, milestones, upcoming features |
| Current project status, recent changes, health |
| Architecture decisions, trade-offs, rationale |
| Active task files (10-30 items, YAML frontmatter) |
| 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 sourcesHow It Works
User query: "What's the project status?"
Intent detection: Keywords "status" → intent
planSource 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 namesExample: 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.
Available Tools
42 toolsadd_decisionA
Adds a single architecture decision record (ADR) to DECISIONS.md. Creates a structured entry with title, context, decision, and consequences sections.
Inputs: title (required), decision (required), context, consequences, +2 more.
add_roadmap_milestoneA
Adds a milestone or phase to ROADMAP.md. Creates a structured entry with title, description, target date, and deliverables.
Inputs: title (required), description, target_date, deliverables, +1 more.
add_to_backlogA
Adds a single item to BACKLOG.md. Use this for quick task creation without bulk import. Items are added to the specified priority section and can later be promoted to active work.
Inputs: title (required), project (required), priority, tags, +2 more.
archive_taskA
Archives a completed task by moving it from todos/ to archive/. Keeps the active task queue small and focused. Archived tasks are preserved for history but excluded from get_next_task.
Inputs: task_id (required), force.
archive_thoughtA
Archives a processed thought file by moving it to .project/thoughts/todos/.archive/. Use this after you've created tasks from a thought file to keep the active thoughts folder clean. Also logs the archive action with timestamp and created task IDs.
Inputs: file (required), created_tasks, notes.
check_project_stateA
Checks the current state of project management files. Returns which files exist (.project/index.md, ROADMAP.md, TODO.md, STATUS.md, DECISIONS.md) and provides a summary of project state. Use this before making changes to understand what exists.
Inputs: no named parameters.
create_or_update_decisionsB
Creates or updates the DECISIONS.md file in .project/ directory. Use this when documenting architecture decisions, trade-offs, or rationale. Helps maintain a decision log for the project.
Inputs: content (required), decisionTitle, replace.
create_or_update_indexB
Creates or updates the index.md file in .project/ directory. This is the contract file that defines how agents should interpret sources. Use this when setting up project structure or updating source mappings.
Inputs: content (required), replace.
create_or_update_roadmapA
Creates or updates the ROADMAP.md file in .project/ directory. Use this when planning future work, milestones, or phases. If the file exists, intelligently merges new content with existing roadmap.
Inputs: content (required), section, replace.
create_or_update_statusA
Creates or updates the STATUS.md file in .project/ directory. Use this when updating project health, recent changes, metrics, or current phase. Automatically updates the "Last Updated" timestamp.
Inputs: content (required), updateType, replace.
create_or_update_todoA
Creates or updates the TODO.md file in .project/ directory. Use this when adding tasks, marking items complete, or updating task status. Intelligently organizes tasks into sections (In Progress, Next Up, Blocked, Completed).
Inputs: content (required), section, markComplete, replace.
create_taskA
Creates a new task with YAML frontmatter metadata. Uses Jira-like IDs (e.g., AUTH-001, API-042) for stable references. Supports dependencies, priorities, estimates, due dates, and tags. Agents can determine execution order by checking dependencies and priorities.
Inputs: title (required), project (required), description, owner, +8 more.
delete_taskA
Permanently deletes a task from todos/. Use with caution - this cannot be undone. Consider using archive_task instead for completed tasks.
Inputs: id (required), confirm.
get_backlogA
Reads and returns the current backlog contents with optional filtering. Shows tasks organized by priority with counts and summary.
Inputs: priority, project, include_promoted.
get_decisionA
Reads a specific architecture decision by ADR ID. Returns the full decision content including context, decision, and consequences.
Inputs: id (required).
get_docA
Get the full content of a specific file. Supports files from .project/, root-level, or docs/. Use the path as returned from search results.
Inputs: path (required).
get_doc_structureA
Get the complete documentation directory structure with file paths and descriptions. Useful for understanding the organization of documentation.
Inputs: no named parameters.
get_next_taskA
Returns the next task(s) that should be worked on. Considers: dependencies (only returns tasks whose dependencies are done), priority (P0 first), status (excludes done/blocked), and optionally filters by owner or project. This is the key tool for agentic execution - call this to know what to do next.
Inputs: owner, project, include_blocked, limit.
get_roadmapA
Reads the current roadmap content from ROADMAP.md. Returns milestones, phases, and planned work.
Inputs: section.
get_taskA
Reads and returns a specific task by ID. Shows all metadata including frontmatter, description, subtasks, and notes.
Inputs: id (required).
get_thoughtC
Reads a specific thought file and returns its raw content for review.
Inputs: file (required), category, from_archive.
import_tasksA
Parses a plan document and imports tasks to BACKLOG.md (not individual files). Use this to populate the backlog from a roadmap or requirements doc. Tasks stay in BACKLOG until promoted to active work via promote_task.
Inputs: source (required), project (required), source_type, phase, +2 more.
init_projectA
Initializes the .project/ directory with all standard files following strict templates. Creates index.md (contract), TODO.md (dashboard), BACKLOG.md (prioritized work queue), ROADMAP.md, STATUS.md, DECISIONS.md, and todos/ directory. Use this to bootstrap a new project with proper structure.
Inputs: project_name (required), project_description, overwrite.
lint_project_docsA
Validates project documentation against standards. Checks for required files, valid frontmatter, broken dependencies, missing fields, and formatting issues. Can auto-fix common problems. Run this before commits to ensure documentation quality.
Inputs: fix, strict, scope.
list_archived_tasksB
Lists tasks in the archive/ directory. Shows completed work history with optional filtering by project or date.
Inputs: project, limit.
list_archived_thoughtsA
Lists all archived thought files with their processing history. Shows what thoughts were processed, when, and what tasks were created.
Inputs: limit.
list_decisionsA
Lists all architecture decisions from DECISIONS.md with optional filtering by status or tag.
Inputs: status, tag.
list_docsA
List all available documentation files organized by category. Use this to discover what documentation is available or to get an overview of the documentation structure.
Inputs: category.
list_tasksB
Lists all tasks with optional filtering. Returns a summary view of tasks organized by status and priority.
Inputs: project, owner, status, priority, +1 more.
list_thoughtsB
Lists all thought files in the .project/thoughts/ directory structure. Shows available brain dump files organized by category.
Inputs: category, include_archived.
manage_project_fileA
Smart tool that automatically determines which project file to create or update based on context. Use this when making changes to the project - it will check project state and determine if index.md, ROADMAP.md, TODO.md, STATUS.md, or DECISIONS.md should be created/updated. This is the primary tool for managing project documentation during development.
Inputs: action (required), content (required), fileType.
process_thoughtsA
Reads brain dump markdown files from .project/thoughts/todos/ and returns the content along with project context for analysis.
This tool gathers:
Raw thought content - The unstructured brain dump as written
Project context - Existing tasks, roadmap milestones, decisions for reference
Task format guide - The YAML structure for creating tasks
YOU (the LLM) should then analyze the content to:
Understand the user's intent (explicit, shadow/underlying, practical)
Identify logical task groupings (consolidate related items)
Determine appropriate priorities based on context
Create well-structured tasks using create_task
After creating tasks, use archive_thought to archive the processed file
The tool does NOT automatically create tasks - it provides you with everything needed to make intelligent decisions about task creation.
Inputs: project (required), file.
promote_taskA
Promotes a task from BACKLOG.md to an active YAML task file in todos/. Use this when starting work on a backlog item. Creates a full task file with YAML frontmatter, dependencies, and metadata.
Inputs: task_id (required), owner, priority, depends_on, +2 more.
remove_from_backlogA
Removes an item from BACKLOG.md without promoting it. Use for tasks that are no longer needed or were added by mistake.
Inputs: task_id (required), reason.
search_docsA
Search only the docs/ directory for reference documentation. Use this when the user specifically asks for "docs" or "documentation". Returns relevant documentation chunks with file paths and content snippets.
Inputs: query (required), category, maxResults.
search_projectA
Search across project sources with smart intent detection. IMPORTANT: "project docs" means APPLICATION documentation (docs/ + DECISIONS.md), NOT project management. Use intent "project_docs" when user says "project docs/documents/documentation" to search application documentation. Use intent "plan" for project management (status, todos, roadmap, backlog).
Inputs: query (required), intent, maxResults.
search_tasksB
Search tasks by keyword in title, description, or content. Returns matching tasks with relevance ranking.
Inputs: query (required), project, status, include_archived, +1 more.
sync_todo_indexA
Syncs the parent TODO.md file with all tasks. Generates a dashboard view with tasks organized by status, priority counts, dependency graph, and execution order. This provides a bird's eye view of all work.
Inputs: format.
unarchive_taskA
Restores a task from archive/ back to todos/ for further work. Use when a completed task needs to be reopened.
Inputs: task_id (required), status.
update_backlog_itemA
Updates an item in BACKLOG.md. Can change priority, title, tags, or phase without promoting to active work.
Inputs: task_id (required), title, priority, tags, +1 more.
update_project_statusC
Quick status update for the project. Adds a timestamped entry to STATUS.md with the current status, changes, or notes.
Inputs: status (required), health, changes, blockers, +1 more.
update_taskB
Updates an existing task by ID. Can update any field including status, priority, owner, dependencies, etc. Use this to transition tasks through workflow states.
Inputs: id (required), title, description, owner, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
Most tools have clear, distinct purposes (e.g., create_task, archive_task, get_task). A few tools like manage_project_file vs specific create/update tools could cause minor confusion, but descriptions clarify their roles.
Predominantly uses verb_noun pattern (create_task, get_task, delete_task). Some variations like add_ vs create_or_update_ and manage_project_file, but overall consistent and readable.
42 tools is on the higher end, but each tool serves a distinct purpose in project management (CRUD for tasks, backlog, decisions, roadmap, etc.). Slightly over but reasonable given the comprehensive scope.
Covers full lifecycle for tasks, backlog, decisions, roadmap, status, documentation, and thoughts. Includes search, linting, and import/export features. No obvious gaps for project management.
Maintenance
Related MCP Connectors
AI-native project management for tasks, docs, collaboration, and agents.
Shared project docs, task planning and GitHub evidence for people and their AI agents.
Project management for AI agents: tasks, docs, decisions and time in one shared team context.
Tasks, sprints, releases and docs for engineering teams with AI coding agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server providing comprehensive task management capabilities with support for project organization, task tracking, and automatic PRD parsing into actionable items.38MIT
- AlicenseNot gradedqualityDmaintenanceAn intelligent task management server that generates context-aware engineering plans using LLM-powered workflows and interactive requirement elicitation. It features persistent SQLite storage, category-based planning strategies, and automated progress tracking for software development projects.MIT

Version Pill MCPofficial
FlicenseNot gradedqualityDmaintenanceAI-native project management server for coding agents, offering 60 tools for tasks, releases, epics, cycles, docs, and ideas with caching and agent memory.-- FlicenseNot gradedqualityBmaintenanceA local-first MCP server and CLI that gives coding agents structured project memory, task contracts, context packs, backlog workflows, and verification evidence, storing data in reviewable Markdown/YAML with a fast SQLite index.4-