Project MCP

An intent-based MCP server for automatically mapping natural language queries to the correct sources of project documents, supporting intelligent search, task management, and project document organization.

Developer tools Knowledge management and memory #Project documents #Intent search #Task management #MCP service .JavaScript

rating : 2.5 points

downloads : 7.2K

update time : 2026-03-13

Open Site

What is Project MCP?

Project MCP is an intelligent Model Context Protocol server dedicated to managing and searching project documents. It uses natural language understanding technology to automatically recognize user query intentions and route queries to the correct document sources. This means that users can use natural language (such as 'How is the project status?' or 'View documents') without knowing the specific file paths or directory structures.

How to use Project MCP?

Using Project MCP is very simple: First, install it via npm, then add the server configuration to the MCP configuration file. After the configuration is completed, the AI assistant (such as Claude Desktop) can automatically understand your project-related queries and search for the correct document sources. You just need to ask for project information as usual, and the server will automatically handle intent recognition and document search.

Use cases

Project MCP is particularly suitable for the following scenarios: 1. Development teams need to quickly access project documents and status. 2. Project managers need to view project progress and to-do lists. 3. New team members need to understand the project architecture and decision records. 4. Scenarios that require automated project document search and management. 5. Users who want to interact with project documents using natural language.

Main features

Intelligent intent mapping

Automatically recognize user query intentions and map natural language to the correct document sources. For example, when users say 'project', it searches the.project/ directory, root directory files, and the docs/ directory; when users say 'document', it only searches the docs/ directory.

Complete task management system

Provide a complete task workflow from planning to archiving: Roadmap → To-do list → Active tasks → Archive. Support task dependencies, priority sorting, and status tracking.

Automatic discovery and indexing

Automatically discover and index the project document structure, including the.project/ directory, root directory Markdown files, and the docs/ directory, without manual configuration of document sources.

37 dedicated tools

Provide 37 specially designed tools covering various aspects such as search, project management, to-do list management, task management, archiving, decision records, and quality checks.

Structured workflow

A clearly defined task management process: Planning (ROADMAP.md) → To-do list (BACKLOG.md) → Active tasks (todos/*.md) → Archive (archive/), ensuring orderly work.

Task dependency tracking

Support dependencies between tasks. The get_next_task tool only returns tasks whose dependencies are satisfied, ensuring the correct work order.

Advantages

Intelligent intent recognition: Users can use natural language without memorizing directory structures.

Zero-configuration startup: Automatically discover and index project documents, ready to use out of the box.

Complete workflow: A complete task management solution from planning to archiving.

Flexible document structure: Support custom document directories and working directories.

Rich toolset: 37 dedicated tools meet various project management needs.

Clear separation of responsibilities:.project/ is used for operational status, and docs/ is used for reference documents.

Limitations

Requires a Node.js environment: Must run in an environment that supports Node.js.

Learning curve: Need to understand the task management workflow and concepts.

File structure dependency: Depends on specific directory structures (such as.project/, docs/, etc.).

Initial setup: Although it is zero-configuration, still need to add the server to the MCP configuration.

Only supports Markdown: Mainly processes documents in Markdown format.

How to use

Install Project MCP

Install the Project MCP package globally or locally via npm.

Configure the MCP server

Add the Project MCP server configuration to the.mcp.json configuration file of the project.

Initialize the project structure

Use the init_project tool to create a standard project document structure.

Start using natural language queries

Now you can use natural language to query project information, such as 'How is the project status?' or 'View to-do items'.

Usage examples

Example 1: New team member learns about the project

A newly joined developer needs to quickly understand the project status, architecture, and current work priorities.

Example 2: Project manager checks progress

The project manager needs to view the overall project progress, blocking issues, and the next plan.

Example 3: Developer gets the next task

After completing the current task, the developer needs to know which task to handle next.

Example 4: Record technical decisions

The team needs to record important technical decisions and the reasons for the choices.

Frequently Asked Questions

What document formats does Project MCP support?

How to customize the document directory?

How does Project MCP handle task dependencies?

Is there a limit to the number of active tasks?

What is the difference between Project MCP and ordinary file search?

Do I need to manually create all project files?

Related resources

GitHub repository

Project source code, issue tracking, and contribution guidelines.

npm package page

npm package information and installation instructions.

Model Context Protocol official website

Official documentation and specifications of the MCP protocol.

Usage examples

Detailed usage examples and patterns.

Contribution guidelines

How to contribute code and documentation to the project.

🚀 project-mcp

An intent-based MCP server for project documentation that automatically maps natural language to the right sources.

When users say "project", "docs", or "todos", project-mcp automatically searches the right directories without any configuration required. It understands the user's intent, not just directory names.

🚀 Quick Start

📦 Installation

npm install project-mcp

⚙️ Configuration

Add the following to .mcp.json:

{
    "mcpServers": {
        "project": {
            "command": "npx",
            "args": ["-y", "project-mcp"]
        }
    }
}

That's it. The server will automatically find and index the following:

.project/ — Operational truth (plans, todos, status)
Root markdown files — README.md, DEVELOPMENT.md, etc.
docs/ — Reference documentation

✨ Features

🎯 Why project-mcp?

The Problem: AI agents need to search project documentation, but:

Users say "project" instead of ".project/"
Different queries require different sources
Manual source mapping is error-prone
There is no standard way to organize project knowledge

The Solution: Intent-based search that automatically maps language to sources:

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

💻 Usage Examples

🔍 Basic Usage

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

🚀 Advanced Usage

{
    "tool": "import_tasks",
    "arguments": {
        "source": ".project/ROADMAP.md",
        "project": "APP",
        "dry_run": true
    }
}

📋 Task Management System

🔄 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