Intent-based MCP server for project documentation search. Maps natural language queries to the right sources automatically—no configuration needed. The standard for AI agent documentation search.
npm install 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.
---
``bash`
npm install project-mcp
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)docs/
- Root markdown files — README.md, DEVELOPMENT.md, etc.
- — Reference documentation
---
- project-mcp
- ⚡ Quick Start
- Install
- Configure
- Table of Contents
- 🎯 Why project-mcp?
- 🛠️ Available Tools (37)
- Search Tools
- Project Management Tools
- Backlog Tools
- Task Management Tools
- Archive Tools
- Decision \& Status Tools
- Quality Tools
- 📋 Task Management System
- Workflow
- Task File Format (Active Tasks)
- Agent Execution Loop
- Key Features
- 🏗️ Project Structure Guide
- Recommended Directory Structure
- What Goes Where?
- .project/ — Operational Truth
- docs/ — Reference Truth
- 🎨 Intent Mapping
- How It Works
- 📝 Documentation Examples
- Example: .project/index.md (Contract File)
- Example: Task Creation
- Example: Getting Next Task
- Example: Initialize Project
- Example: Import Tasks to Backlog
- Example: Promote Task to Active Work
- Example: Archive Completed Task
- ⚙️ Configuration
- Custom Documentation Directory
- Custom Working Directory
- 🧪 Development
- 📚 Documentation
- 🤝 Contributing
- 📄 License
---
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/
| "docs" / "documentation" | Only |.project/
| "plan" / "todos" / "roadmap" / "status" | Only |
---
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Tool | Description | Use When |
| ------------------- | ---------------------------------------- | -------------------------------- |
| lint_project_docs | Validate documentation against standards | Before commits, ensuring quality |
---
Tasks flow from planning → backlog → active → archive. Only active tasks
(10-30 items) are YAML files.
`
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.md
| Backlog | | Prioritized queue, hundreds of items OK |todos/*.md
| Active | | YAML files with full metadata, 10-30 items |archive/*.md
| Archive | | Completed work history |
`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
---
Implement OAuth 2.0 authentication flow...
- [ ] Set up OAuth provider
- [ ] Implement callback handler
- [x] Configure environment variables
$3
┌─────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────────────────────────────────────────┘
$3
- Backlog-first: Plan hundreds of items in
, 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: → in_progress → blocked | review → done
- Archive history: Completed work preserved in for reference---
🏗️ Project Structure Guide
$3
`
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
$3
####
— Operational TruthPurpose: 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 TruthPurpose: 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
$3
1. User query: "What's the project status?"
2. Intent detection: Keywords "status" → intent
3. Source mapping: → searches only .project/
4. Results: Returns , .project/TODO.md, etc.---
📝 Documentation Examples
$3
`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 documentationPrinciples
- 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
`$3
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"]
}
}
`$3
json
{
"tool": "get_next_task",
"arguments": {
"owner": "cursor",
"limit": 3
}
}
`Returns tasks sorted by priority where all dependencies are complete.
$3
json
{
"tool": "init_project",
"arguments": {
"project_name": "My App",
"project_description": "A web application for task management"
}
}
`Creates
with all standard files: index.md, TODO.md,
ROADMAP.md, STATUS.md, DECISIONS.md, and todos/ directory.$3
`json
{
"tool": "import_tasks",
"arguments": {
"source": ".project/ROADMAP.md",
"project": "APP",
"dry_run": true
}
}
`Parses the roadmap and adds tasks to
. Use dry_run: true to
preview first.$3
`json
{
"tool": "promote_task",
"arguments": {
"task_id": "APP-001",
"owner": "cursor",
"estimate": "2h"
}
}
`Moves task from
to todos/APP-001.md with full YAML frontmatter.$3
`json
{
"tool": "archive_task",
"arguments": {
"task_id": "APP-001"
}
}
`Moves completed task from
to archive/ to keep active queue small.---
⚙️ Configuration
$3
`json
{
"mcpServers": {
"project": {
"command": "npx",
"args": ["-y", "project-mcp"],
"env": {
"DOCS_DIR": "/path/to/documentation"
}
}
}
}
`$3
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-mcpInstall dependencies
npm installRun tests
npm testTest the server
node src/index.js
``---
- Examples — Usage examples and patterns
- Contributing — How to contribute
- Security — Security policy
- Changelog — Version history
- Release Notes v2.0.0 — Latest
release
---
Contributions welcome! See CONTRIBUTING.md for guidelines.
---
MIT License - see LICENSE for details.
---