# project-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/pouyanafisi/project-mcp  
**GitHub Stars:** 9  
**npm Downloads (last month):** 2805  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/project-mcp

## Description
Intent-based search over a project's documentation and todo files for AI agents. Local stdio server.

## Tools
Capabilities this server exposes over MCP:

- **search_project** — 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).
- **search_docs** — 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.
- **get_doc** — Get the full content of a specific file. Supports files from .project/, root-level, or docs/. Use the path as returned from search results.
- **list_docs** — 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.
- **get_doc_structure** — Get the complete documentation directory structure with file paths and descriptions. Useful for understanding the organization of documentation.
- **manage_project_file** — 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.
- **check_project_state** — 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.
- **create_or_update_roadmap** — 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.
- **create_or_update_todo** — 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).
- **create_or_update_status** — 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.
- **create_or_update_index** — 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.
- **create_or_update_decisions** — 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.
- **add_decision** — Adds a single architecture decision record (ADR) to DECISIONS.md. Creates a structured entry with title, context, decision, and consequences sections.
- **list_decisions** — Lists all architecture decisions from DECISIONS.md with optional filtering by status or tag.
- **update_project_status** — Quick status update for the project. Adds a timestamped entry to STATUS.md with the current status, changes, or notes.
- **add_roadmap_milestone** — Adds a milestone or phase to ROADMAP.md. Creates a structured entry with title, description, target date, and deliverables.
- **get_decision** — Reads a specific architecture decision by ADR ID. Returns the full decision content including context, decision, and consequences.
- **get_roadmap** — Reads the current roadmap content from ROADMAP.md. Returns milestones, phases, and planned work.
- **create_task** — 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.
- **update_task** — Updates an existing task by ID. Can update any field including status, priority, owner, dependencies, etc. Use this to transition tasks through workflow states.
- **get_task** — Reads and returns a specific task by ID. Shows all metadata including frontmatter, description, subtasks, and notes.
- **delete_task** — Permanently deletes a task from todos/. Use with caution - this cannot be undone. Consider using archive_task instead for completed tasks.
- **get_next_task** — 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.
- **list_tasks** — Lists all tasks with optional filtering. Returns a summary view of tasks organized by status and priority.
- **search_tasks** — Search tasks by keyword in title, description, or content. Returns matching tasks with relevance ranking.
- **sync_todo_index** — 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.
- **import_tasks** — 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.
- **promote_task** — 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.
- **archive_task** — 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.
- **add_to_backlog** — 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.
- **get_backlog** — Reads and returns the current backlog contents with optional filtering. Shows tasks organized by priority with counts and summary.
- **update_backlog_item** — Updates an item in BACKLOG.md. Can change priority, title, tags, or phase without promoting to active work.
- **remove_from_backlog** — Removes an item from BACKLOG.md without promoting it. Use for tasks that are no longer needed or were added by mistake.
- **list_archived_tasks** — Lists tasks in the archive/ directory. Shows completed work history with optional filtering by project or date.
- **unarchive_task** — Restores a task from archive/ back to todos/ for further work. Use when a completed task needs to be reopened.
- **lint_project_docs** — 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.
- **init_project** — 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.
- **process_thoughts** — 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.
- **archive_thought** — 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.
- **list_thoughts** — Lists all thought files in the .project/thoughts/ directory structure. Shows available brain dump files organized by category.
- **list_archived_thoughts** — Lists all archived thought files with their processing history. Shows what thoughts were processed, when, and what tasks were created.
- **get_thought** — Reads a specific thought file and returns its raw content for review.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What project-mcp MCP server does

project-mcp provides an MCP interface for project documentation and work tracking stored in local files. It recognizes terms such as “project,” “docs,” “plan,” “todos,” “roadmap,” and “status,” then selects relevant sources instead of searching every directory indiscriminately.

The default sources are `.project/` for operational information, Markdown files at the repository root, and `docs/` for reference material. The server can also initialize the `.project/` structure and create or update common project records such as roadmaps, todos, status reports, decisions, and an index file.

## How it works

The server runs locally over stdio. Its intent mapping determines which files to search:

- Project-oriented requests search `.project/`, root files, and `docs/`.
- Documentation requests search `docs/` only.
- Planning and status requests search `.project/` only.

Search is only one part of the interface. Tools can list documentation, retrieve a known file, inspect the directory structure, and search tasks by title or content. Other operations modify Markdown files and task records, including adding backlog items, promoting work into active tasks, updating task fields, and generating a TODO dashboard.

## Setup and configuration

Install the npm package with `npm install project-mcp`. Configure an MCP client to launch it through `npx -y project-mcp` using a local stdio server entry, such as the following:

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

No environment variables are required by the documented setup. After launch, project-mcp discovers and indexes the supported directories automatically.

## Tools and capabilities

The documented tool groups cover:

- Searching project sources and reference documentation.
- Reading individual files and listing documentation or categories.
- Initializing project metadata and checking its current state.
- Creating or updating roadmaps, todos, status files, decisions, and index files.
- Creating, updating, filtering, importing, promoting, and removing backlog items.
- Creating, reading, searching, updating, deleting, and archiving tasks.
- Creating and updating documentation, architecture records, and release notes.
- Finding the next dependency-aware task and synchronizing the TODO index.

Use the search tools when an agent needs project context. Use the management tools when the agent is expected to maintain the repository’s planning or task files rather than only read them.

## Limitations and notes

Its intent routing depends on the vocabulary mapped to each source group, so queries that do not indicate a project, documentation, planning, or status context may require a more specific tool.

The documented setup exposes project-mcp as a local stdio process. Client-specific configuration beyond the `.mcp.json` example is not described. The package is distributed under the MIT license.

_Full upstream README: https://allmcps.com/mcp/project-mcp/readme_