Skip to main content
Glama

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

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

.project/ + root files + docs/

"docs" / "documentation"

Only docs/

"plan" / "todos" / "roadmap" / "status"

Only .project/


🛠️ Available Tools (47)

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

Documentation Tools

Tool

Description

Use When

create_doc

Create new doc in docs/

Adding application documentation

update_doc

Update existing doc in docs/

Modifying reference docs

add_release_note

Add versioned release notes

Documenting releases

update_architecture_doc

Create/update architecture docs

Documenting system design

list_doc_categories

List documentation categories

Understanding docs structure

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

Thoughts Tools

Tool

Description

Use When

process_thoughts

Process brain dump files into tasks

Converting notes to actionable tasks

archive_thought

Archive processed thought files

Cleaning up processed notes

list_thoughts

List unprocessed thought files

Reviewing pending brain dumps

list_archived_thoughts

List processed thought history

Reviewing what was processed

get_thought

Read specific thought file

Viewing thought content

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

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)

# 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


🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.


📄 License

MIT License - see LICENSE for details.


Get Started • Documentation • Examples • Report Issue

Available Tools

42 tools
add_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:

  1. Raw thought content - The unstructured brain dump as written

  2. Project context - Existing tasks, roadmap milestones, decisions for reference

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

    A3.7/5.0

    Scored across 42 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers