project

project-mcp is an intent-based MCP server that automatically indexes and searches project documentation across multiple sources. When a user mentions terms like 'project', 'docs', or 'todos', the server maps the query to the most relevant sources without requiring manual configuration. It indexes the .project/ directory (for operational truth like plans and todos), root Markdown files (e.g., README.md, DEVELOPMENT.md), and the docs/ directory for reference material. This enables fast, intent-driven access to a broad set of project information through a unified interface.

The server exposes a suite of tools designed for project knowledge management. Under Search Tools, you can perform intent-based searches across all sources (search_project), limit results to the reference docs (search_docs), retrieve full file contents (get_doc), list available documentation files (list_docs), or extract the current directory structure (get_doc_structure). For project management, there are tools to initialize and update project files, create or update roadmaps, todos, statuses, indices, and decisions, and to check the current state of the project files. Backlog tools support adding, reading, updating, removing, and bulk importing tasks. Task management tools let you create, read, update, delete, search, and organize tasks, while backlog-to-active task workflows help move work through the lifecycle. This combination enables end-to-end project knowledge management directly from natural language prompts.

To use the server, configure it according to the repository's .mcp.json example, then start the server via the npm/npx command provided. Once running, you can issue natural language queries to search across your project sources, or invoke specific tools to perform structured actions such as creating a new task, updating a roadmap, or retrieving a particular document.

Prerequisites:

• Node.js (LTS version) and npm installed on your machine
• Basic familiarity with npm and running CLI tools

Step-by-step installation:

1. Install Node.js and npm from https://nodejs.org/ if not already installed.
2. Install the MCP server package locally (or globally): npm install project-mcp
3. Create a configuration file for MCP. For example, add a .mcp.json with the following content: { "mcpServers": { "project": { "command": "npx", "args": ["-y", "project-mcp"] } } }
4. Start the MCP server via the configured command. If you used the example above, run: npx -y project-mcp
5. The server will index the following locations by default:
   • .project/ (operational truth like plans, todos, status)
   • Root Markdown files (README.md, DEVELOPMENT.md, etc.)
   • docs/ (reference documentation)
6. Interact with the server using MCP-compatible clients or the tooling provided by the package.

Tips and common issues:

• Ensure your project structure contains the expected directories (.project/, docs/, and Markdown files) for optimal indexing.
• If you modify the configuration, restart the MCP server to re-index sources.
• The server defaults to indexing root Markdown files and documents under docs/; customize paths if your project uses a different layout.
• For troubleshooting, verify Node.js/npm versions, and ensure network permissions allow the server to access local filesystem paths.
• The npm_package value is project-mcp, and the server is intended to be run via npx as shown in the Quick Start example.