project-mcp 3.0.0 → 3.2.0

package/README.md

@@ -14,58 +14,15 @@ not just directory names.
 
 ---
 
-## Table of Contents
-
-- [project-mcp](#project-mcp)
-	- [Table of Contents](#table-of-contents)
-	- [⚡ Quick Start](#-quick-start)
-		- [Install](#install)
-		- [Configure](#configure)
-	- [🎯 Why project-mcp?](#-why-project-mcp)
-	- [🛠️ Available Tools](#️-available-tools)
-		- [Search Tools](#search-tools)
-		- [Project Management Tools](#project-management-tools)
-		- [Task Management Tools](#task-management-tools)
-		- [Quality Tools](#quality-tools)
-	- [📋 Task Management System](#-task-management-system)
-		- [Workflow](#workflow)
-		- [Task File Format (Active Tasks)](#task-file-format-active-tasks)
-		- [Agent Execution Loop](#agent-execution-loop)
-		- [Key Features](#key-features)
-	- [🏗️ Project Structure Guide](#️-project-structure-guide)
-		- [Recommended Directory Structure](#recommended-directory-structure)
-		- [What Goes Where?](#what-goes-where)
-			- [`.project/` — Operational Truth](#project--operational-truth)
-			- [`docs/` — Reference Truth](#docs--reference-truth)
-	- [🎨 Intent Mapping](#-intent-mapping)
-		- [How It Works](#how-it-works)
-	- [📝 Documentation Examples](#-documentation-examples)
-		- [Example: `.project/index.md` (Contract File)](#example-projectindexmd-contract-file)
-		- [Example: Task Creation](#example-task-creation)
-		- [Example: Getting Next Task](#example-getting-next-task)
-		- [Example: Initialize Project](#example-initialize-project)
-		- [Example: Import Tasks to Backlog](#example-import-tasks-to-backlog)
-		- [Example: Promote Task to Active Work](#example-promote-task-to-active-work)
-		- [Example: Archive Completed Task](#example-archive-completed-task)
-	- [⚙️ Configuration](#️-configuration)
-		- [Custom Documentation Directory](#custom-documentation-directory)
-		- [Custom Working Directory](#custom-working-directory)
-	- [🧪 Development](#-development)
-	- [📚 Documentation](#-documentation)
-	- [🤝 Contributing](#-contributing)
-	- [📄 License](#-license)
-
----
-
-## ⚡ Quick Start
+# ⚡ Quick Start
 
-### Install
+## Install
 
 ```bash
 npm install project-mcp
 ```
 
-### Configure
+## Configure
 
 Add to `.mcp.json`:
 
@@ -88,6 +45,52 @@ Add to `.mcp.json`:
 
 ---
 
+## Table of Contents
+
+- [project-mcp](#project-mcp)
+- [⚡ Quick Start](#-quick-start)
+  - [Install](#install)
+  - [Configure](#configure)
+  - [Table of Contents](#table-of-contents)
+  - [🎯 Why project-mcp?](#-why-project-mcp)
+  - [🛠️ Available Tools (37)](#️-available-tools-37)
+    - [Search Tools](#search-tools)
+    - [Project Management Tools](#project-management-tools)
+    - [Backlog Tools](#backlog-tools)
+    - [Task Management Tools](#task-management-tools)
+    - [Archive Tools](#archive-tools)
+    - [Decision \& Status Tools](#decision--status-tools)
+    - [Quality Tools](#quality-tools)
+  - [📋 Task Management System](#-task-management-system)
+    - [Workflow](#workflow)
+    - [Task File Format (Active Tasks)](#task-file-format-active-tasks)
+    - [Agent Execution Loop](#agent-execution-loop)
+    - [Key Features](#key-features)
+  - [🏗️ Project Structure Guide](#️-project-structure-guide)
+    - [Recommended Directory Structure](#recommended-directory-structure)
+    - [What Goes Where?](#what-goes-where)
+      - [`.project/` — Operational Truth](#project--operational-truth)
+      - [`docs/` — Reference Truth](#docs--reference-truth)
+  - [🎨 Intent Mapping](#-intent-mapping)
+    - [How It Works](#how-it-works)
+  - [📝 Documentation Examples](#-documentation-examples)
+    - [Example: `.project/index.md` (Contract File)](#example-projectindexmd-contract-file)
+    - [Example: Task Creation](#example-task-creation)
+    - [Example: Getting Next Task](#example-getting-next-task)
+    - [Example: Initialize Project](#example-initialize-project)
+    - [Example: Import Tasks to Backlog](#example-import-tasks-to-backlog)
+    - [Example: Promote Task to Active Work](#example-promote-task-to-active-work)
+    - [Example: Archive Completed Task](#example-archive-completed-task)
+  - [⚙️ Configuration](#️-configuration)
+    - [Custom Documentation Directory](#custom-documentation-directory)
+    - [Custom Working Directory](#custom-working-directory)
+  - [🧪 Development](#-development)
+  - [📚 Documentation](#-documentation)
+  - [🤝 Contributing](#-contributing)
+  - [📄 License](#-license)
+
+---
+
 ## 🎯 Why project-mcp?
 
 **The Problem:** AI agents need to search project documentation, but:
@@ -108,7 +111,7 @@ automatically:
 
 ---
 
-## 🛠️ Available Tools
+## 🛠️ Available Tools (37)
 
 ### Search Tools
 
@@ -133,18 +136,48 @@ automatically:
 | `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                        |
-| ----------------- | ---------------------------------------------------- | ------------------------------- |
-| `import_tasks`    | Parse plan/roadmap and add to BACKLOG.md             | Populating the backlog          |
-| `promote_task`    | Move task from BACKLOG to active work (creates YAML) | Starting work on a backlog item |
-| `create_task`     | Create active task directly (bypass backlog)         | Urgent/immediate work           |
-| `update_task`     | Update any task field, transition status             | Modifying existing tasks        |
-| `get_next_task`   | Get dependency-aware next task(s) to work on         | Determining what to do next     |
-| `list_tasks`      | List/filter tasks with summary dashboard             | Reviewing all tasks             |
-| `archive_task`    | Move completed task to archive/                      | Cleaning up done work           |
-| `sync_todo_index` | Generate TODO.md dashboard from active tasks         | Updating the overview           |
+| 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
 
@@ -404,7 +437,7 @@ Returns tasks sorted by priority where all dependencies are complete.
 	"arguments": {
 		"project_name": "My App",
 		"project_description": "A web application for task management"
-  }
+	}
 }
 ```
 
@@ -505,7 +538,7 @@ npm install
 npm test
 
 # Test the server
-node index.js
+node src/index.js
 ```
 
 ---
@@ -516,7 +549,8 @@ node index.js
 - **[Contributing](CONTRIBUTING.md)** — How to contribute
 - **[Security](SECURITY.md)** — Security policy
 - **[Changelog](CHANGELOG.md)** — Version history
-- **[Release Notes v1.3.0](docs/releases/RELEASE_NOTES_v1.3.0.md)** — Latest release
+- **[Release Notes v2.0.0](docs/releases/RELEASE_NOTES_v2.0.0.md)** — Latest
+  release
 
 ---
 

package/package.json

@@ -1,79 +1,79 @@
 {
-	"name": "project-mcp",
-	"version": "3.0.0",
-	"description": "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.",
-	"type": "module",
-	"main": "src/index.js",
-	"bin": {
-		"project-mcp": "src/index.js"
-	},
-	"scripts": {
-		"start": "node src/index.js",
-		"test": "node --test test/*.test.js",
-		"lint": "node --check src/index.js",
-		"format": "prettier --write \"**/*.{js,md,json}\"",
-		"format:check": "prettier --check \"**/*.{js,md,json}\"",
-		"prepublishOnly": "npm run lint && npm test"
-	},
-	"keywords": [
-		"mcp",
-		"model-context-protocol",
-		"mcp-server",
-		"documentation",
-		"documentation-search",
-		"docs-search",
-		"search",
-		"fuzzy-search",
-		"semantic-search",
-		"markdown",
-		"markdown-search",
-		"project-documentation",
-		"project-management",
-		"intent-based-search",
-		"intent-mapping",
-		"ai-agent",
-		"ai-assistant",
-		"claude",
-		"cursor",
-		"anthropic",
-		"ai-tools",
-		"developer-tools",
-		"documentation-tools",
-		"knowledge-base",
-		"project-knowledge",
-		"operational-truth",
-		"reference-documentation",
-		"fuse.js",
-		"natural-language",
-		"nlp",
-		"zero-config",
-		"automatic-indexing"
-	],
-	"author": "",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/pouyanafisi/project-mcp.git"
-	},
-	"bugs": {
-		"url": "https://github.com/pouyanafisi/project-mcp/issues"
-	},
-	"homepage": "https://github.com/pouyanafisi/project-mcp#readme",
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.0.4",
-		"fuse.js": "^7.0.0",
-		"gray-matter": "^4.0.3",
-		"mime-types": "^2.1.35"
-	},
-	"devDependencies": {
-		"prettier": "^3.7.4"
-	},
-	"files": [
-		"src/",
-		"README.md",
-		"LICENSE"
-	]
+  "name": "project-mcp",
+  "version": "3.2.0",
+  "description": "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.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "project-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test test/*.test.js",
+    "lint": "node --check src/index.js",
+    "format": "prettier --write \"**/*.{js,md,json}\"",
+    "format:check": "prettier --check \"**/*.{js,md,json}\"",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "documentation",
+    "documentation-search",
+    "docs-search",
+    "search",
+    "fuzzy-search",
+    "semantic-search",
+    "markdown",
+    "markdown-search",
+    "project-documentation",
+    "project-management",
+    "intent-based-search",
+    "intent-mapping",
+    "ai-agent",
+    "ai-assistant",
+    "claude",
+    "cursor",
+    "anthropic",
+    "ai-tools",
+    "developer-tools",
+    "documentation-tools",
+    "knowledge-base",
+    "project-knowledge",
+    "operational-truth",
+    "reference-documentation",
+    "fuse.js",
+    "natural-language",
+    "nlp",
+    "zero-config",
+    "automatic-indexing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pouyanafisi/project-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pouyanafisi/project-mcp/issues"
+  },
+  "homepage": "https://github.com/pouyanafisi/project-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "fuse.js": "^7.0.0",
+    "gray-matter": "^4.0.3",
+    "mime-types": "^2.1.35"
+  },
+  "devDependencies": {
+    "prettier": "^3.7.4"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/src/prompts/definitions.js

@@ -12,7 +12,7 @@
  * @type {Record<string, string[]>}
  */
 export const promptToolMapping = {
-	project_overview: ['check_project_state', 'search_project', 'list_tasks'],
+	project_overview: ['check_project_state', 'search_project', 'list_tasks', 'get_backlog'],
 	get_next_task: ['get_next_task'],
 	init_project: ['init_project'],
 	import_tasks: ['import_tasks'],
@@ -20,6 +20,10 @@ export const promptToolMapping = {
 	lint_project: ['lint_project_docs'],
 	list_tasks: ['list_tasks'],
 	update_task: ['update_task'],
+	add_to_backlog: ['add_to_backlog'],
+	get_backlog: ['get_backlog'],
+	add_decision: ['add_decision'],
+	update_status: ['update_project_status'],
 };
 
 /**
@@ -132,6 +136,74 @@ export const prompts = [
 			},
 		],
 	},
+	{
+		name: 'add_to_backlog',
+		description:
+			'Add a single item to the backlog. Use when user says "add to backlog", "queue this task", "backlog item", or "add future task".',
+		arguments: [
+			{
+				name: 'title',
+				description: 'Title/description of the backlog item',
+				required: true,
+			},
+			{
+				name: 'project',
+				description: 'Project prefix (e.g., AUTH, API)',
+				required: true,
+			},
+			{
+				name: 'priority',
+				description: 'Priority level (P0, P1, P2, P3)',
+				required: false,
+			},
+		],
+	},
+	{
+		name: 'get_backlog',
+		description:
+			'View the current backlog. Use when user asks "show backlog", "what\'s in the queue", "backlog items", or "pending tasks".',
+		arguments: [
+			{
+				name: 'priority',
+				description: 'Filter by priority (P0, P1, P2, P3)',
+				required: false,
+			},
+		],
+	},
+	{
+		name: 'add_decision',
+		description:
+			'Record an architecture decision. Use when user says "record decision", "document decision", "ADR", or "architecture decision".',
+		arguments: [
+			{
+				name: 'title',
+				description: 'Title of the decision',
+				required: true,
+			},
+			{
+				name: 'decision',
+				description: 'The decision that was made',
+				required: true,
+			},
+		],
+	},
+	{
+		name: 'update_status',
+		description:
+			'Update project status. Use when user says "update status", "project status", "status update", or "how\'s the project".',
+		arguments: [
+			{
+				name: 'status',
+				description: 'Current status summary',
+				required: true,
+			},
+			{
+				name: 'health',
+				description: 'Project health (green, yellow, red)',
+				required: false,
+			},
+		],
+	},
 ];
 
 /**

package/src/prompts/index.js

@@ -145,6 +145,67 @@ Valid statuses: todo, in_progress, blocked, review, done`,
 				},
 			},
 		],
+		add_to_backlog: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: `Add "${args.title || '[TITLE]'}" to the backlog.
+
+Use the \`add_to_backlog\` tool with:
+- title: "${args.title || '[TITLE]'}"
+- project: "${args.project || '[PROJECT]'}"
+${args.priority ? `- priority: "${args.priority}"` : '- priority: "P2" (default)'}
+
+This adds the item to BACKLOG.md. Use \`promote_task\` when ready to start work.`,
+				},
+			},
+		],
+		get_backlog: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: `Show the current backlog${args.priority ? ` filtered by priority ${args.priority}` : ''}.
+
+Use the \`get_backlog\` tool${args.priority ? ` with priority: "${args.priority}"` : ''}.
+
+This shows all items in BACKLOG.md organized by priority.`,
+				},
+			},
+		],
+		add_decision: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: `Record an architecture decision: "${args.title || '[TITLE]'}".
+
+Use the \`add_decision\` tool with:
+- title: "${args.title || '[TITLE]'}"
+- decision: "${args.decision || '[DECISION]'}"
+- context: (optional) why this decision was needed
+- consequences: (optional) impact of the decision
+
+This creates an ADR entry in DECISIONS.md.`,
+				},
+			},
+		],
+		update_status: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: `Update project status: "${args.status || '[STATUS]'}".
+
+Use the \`update_project_status\` tool with:
+- status: "${args.status || '[STATUS]'}"
+${args.health ? `- health: "${args.health}"` : ''}
+
+This adds a timestamped status entry to STATUS.md.`,
+				},
+			},
+		],
 	};
 
 	return (
@@ -174,6 +235,10 @@ export function getMessageHandlerKeys() {
 		lint_project: true,
 		list_tasks: true,
 		update_task: true,
+		add_to_backlog: true,
+		get_backlog: true,
+		add_decision: true,
+		update_status: true,
 	};
 	return Object.keys(messages);
 }