project-mcp 3.1.0 → 3.2.0

package/README.md

@@ -14,18 +14,52 @@ not just directory names.
 
 ---
 
+# ⚡ Quick Start
+
+## Install
+
+```bash
+npm install project-mcp
+```
+
+## Configure
+
+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)
+- Root markdown files — README.md, DEVELOPMENT.md, etc.
+- `docs/` — Reference documentation
+
+---
+
 ## Table of Contents
 
 - [project-mcp](#project-mcp)
+- [⚡ Quick Start](#-quick-start)
+  - [Install](#install)
+  - [Configure](#configure)
   - [Table of Contents](#table-of-contents)
-  - [⚡ Quick Start](#-quick-start)
-    - [Install](#install)
-    - [Configure](#configure)
   - [🎯 Why project-mcp?](#-why-project-mcp)
-  - [🛠️ Available Tools](#️-available-tools)
+  - [🛠️ 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)
@@ -57,37 +91,6 @@ not just directory names.
 
 ---
 
-## ⚡ Quick Start
-
-### Install
-
-```bash
-npm install project-mcp
-```
-
-### Configure
-
-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)
-- Root markdown files — README.md, DEVELOPMENT.md, etc.
-- `docs/` — Reference documentation
-
----
-
 ## 🎯 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
 
@@ -505,7 +538,7 @@ npm install
 npm test
 
 # Test the server
-node index.js
+node src/index.js
 ```
 
 ---
@@ -516,7 +549,7 @@ 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 Notes v2.0.0](docs/releases/RELEASE_NOTES_v2.0.0.md)** — Latest
   release
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mcp",
-  "version": "3.1.0",
+  "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",

package/src/tools/backlog.js

@@ -1,6 +1,6 @@
 /**
  * Backlog management tools.
- * Handles: import_tasks, promote_task, archive_task, add_to_backlog, get_backlog, update_backlog_item, remove_from_backlog
+ * Handles: import_tasks, promote_task, archive_task, add_to_backlog, get_backlog, update_backlog_item, remove_from_backlog, list_archived_tasks, unarchive_task
  */
 
 import {
@@ -245,6 +245,46 @@ export const definitions = [
 			required: ['task_id'],
 		},
 	},
+	{
+		name: 'list_archived_tasks',
+		description:
+			'Lists tasks in the archive/ directory. Shows completed work history with optional filtering by project or date.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				project: {
+					type: 'string',
+					description: 'Filter by project prefix.',
+				},
+				limit: {
+					type: 'number',
+					description: 'Maximum number of tasks to return. Default: 20.',
+					default: 20,
+				},
+			},
+		},
+	},
+	{
+		name: 'unarchive_task',
+		description:
+			'Restores a task from archive/ back to todos/ for further work. Use when a completed task needs to be reopened.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				task_id: {
+					type: 'string',
+					description: 'The task ID to unarchive (e.g., "AUTH-001").',
+				},
+				status: {
+					type: 'string',
+					description: 'Status to set on restore. Default: "todo".',
+					enum: ['todo', 'in_progress', 'blocked', 'review'],
+					default: 'todo',
+				},
+			},
+			required: ['task_id'],
+		},
+	},
 ];
 
 /**
@@ -937,6 +977,140 @@ async function removeFromBacklog(args) {
 	};
 }
 
+/**
+ * List archived tasks handler
+ */
+async function listArchivedTasks(args) {
+	const { project, limit = 20 } = args || {};
+
+	await ensureArchiveDir();
+
+	const { readdir } = await import('fs/promises');
+	let files;
+	try {
+		files = await readdir(ARCHIVE_DIR);
+	} catch {
+		return {
+			content: [
+				{
+					type: 'text',
+					text: `⚠️ No archive directory found. Completed tasks will appear here after using \`archive_task\`.`,
+				},
+			],
+		};
+	}
+
+	const mdFiles = files.filter((f) => f.endsWith('.md'));
+	if (mdFiles.length === 0) {
+		return {
+			content: [
+				{ type: 'text', text: `📦 Archive is empty. No completed tasks have been archived yet.` },
+			],
+		};
+	}
+
+	// Load archived tasks
+	const tasks = [];
+	for (const file of mdFiles) {
+		const filePath = join(ARCHIVE_DIR, file);
+		const content = await readFile(filePath, 'utf-8');
+		const parsed = matter(content);
+		tasks.push({
+			...parsed.data,
+			file,
+		});
+	}
+
+	// Filter by project if specified
+	let filtered = tasks;
+	if (project) {
+		filtered = filtered.filter((t) => t.project === project.toUpperCase());
+	}
+
+	// Sort by archived date (newest first)
+	filtered.sort((a, b) => {
+		const aDate = a.archived || a.completed || a.updated || '';
+		const bDate = b.archived || b.completed || b.updated || '';
+		return bDate.localeCompare(aDate);
+	});
+
+	const results = filtered.slice(0, limit);
+
+	let result = `## Archived Tasks\n\n`;
+	result += `**Total:** ${filtered.length} task(s)${filtered.length > limit ? ` (showing ${limit})` : ''}\n\n`;
+
+	if (results.length === 0) {
+		result += `*No archived tasks${project ? ` for project ${project.toUpperCase()}` : ''}.*\n`;
+	} else {
+		result += `| ID | Title | Completed | Archived |\n`;
+		result += `|----|-------|-----------|----------|\n`;
+		for (const task of results) {
+			result += `| ${task.id} | ${task.title?.substring(0, 35)}${task.title?.length > 35 ? '...' : ''} | ${task.completed || '-'} | ${task.archived || '-'} |\n`;
+		}
+	}
+
+	result += `\n---\n**Tools:** \`unarchive_task\` to restore | \`search_tasks\` with \`include_archived: true\` to search`;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
+/**
+ * Unarchive task handler
+ */
+async function unarchiveTask(args) {
+	const { task_id, status = 'todo' } = args;
+
+	await ensureTodosDir();
+	await ensureArchiveDir();
+
+	const id = task_id.toUpperCase();
+	const archiveFile = join(ARCHIVE_DIR, `${id}.md`);
+	const activeFile = join(TODOS_DIR, `${id}.md`);
+
+	if (!(await fileExists(archiveFile))) {
+		return {
+			content: [{ type: 'text', text: `❌ Task ${id} not found in archive/` }],
+			isError: true,
+		};
+	}
+
+	if (await fileExists(activeFile)) {
+		return {
+			content: [{ type: 'text', text: `⚠️ Task ${id} already exists in todos/. Cannot unarchive.` }],
+		};
+	}
+
+	// Read archived task
+	const content = await readFile(archiveFile, 'utf-8');
+	const parsed = matter(content);
+
+	// Update metadata
+	parsed.data.status = status;
+	parsed.data.updated = getISODate();
+	delete parsed.data.archived;
+	if (status !== 'done') {
+		delete parsed.data.completed;
+	}
+
+	const updatedContent = matter.stringify(parsed.content, parsed.data);
+
+	// Move from archive to todos
+	await writeFile(activeFile, updatedContent, 'utf-8');
+	await unlink(archiveFile);
+
+	let result = `## Task Unarchived: ${id}\n\n`;
+	result += `**Title:** ${parsed.data.title}\n`;
+	result += `**Status:** ${status}\n`;
+	result += `**File:** \`todos/${id}.md\`\n\n`;
+	result += `✅ Task restored from archive. It will now appear in \`get_next_task\` and \`list_tasks\`.`;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
 /**
  * Handler map
  */
@@ -948,4 +1122,6 @@ export const handlers = {
 	get_backlog: getBacklog,
 	update_backlog_item: updateBacklogItem,
 	remove_from_backlog: removeFromBacklog,
+	list_archived_tasks: listArchivedTasks,
+	unarchive_task: unarchiveTask,
 };

package/src/tools/project-files.js

@@ -1,7 +1,7 @@
 /**
  * Project file management tools.
  * Handles: manage_project_file, check_project_state, create_or_update_* tools,
- * add_decision, list_decisions, update_project_status, add_roadmap_milestone
+ * add_decision, list_decisions, get_decision, update_project_status, add_roadmap_milestone, get_roadmap
  */
 
 import { PROJECT_DIR, TODO_SECTIONS } from '../lib/constants.js';
@@ -311,6 +311,35 @@ export const definitions = [
 			required: ['title'],
 		},
 	},
+	{
+		name: 'get_decision',
+		description:
+			'Reads a specific architecture decision by ADR ID. Returns the full decision content including context, decision, and consequences.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				id: {
+					type: 'string',
+					description: 'The ADR ID to retrieve (e.g., "ADR-001", "001", or just "1").',
+				},
+			},
+			required: ['id'],
+		},
+	},
+	{
+		name: 'get_roadmap',
+		description:
+			'Reads the current roadmap content from ROADMAP.md. Returns milestones, phases, and planned work.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				section: {
+					type: 'string',
+					description: 'Optional: Return only a specific section/milestone.',
+				},
+			},
+		},
+	},
 ];
 
 /**
@@ -1151,6 +1180,102 @@ async function manageProjectFile(args) {
 	}
 }
 
+/**
+ * Get decision handler
+ */
+async function getDecision(args) {
+	const { id } = args;
+	await ensureProjectDir();
+
+	const decisionsPath = join(PROJECT_DIR, 'DECISIONS.md');
+	if (!(await fileExists(decisionsPath))) {
+		return {
+			content: [{ type: 'text', text: `❌ DECISIONS.md not found.` }],
+			isError: true,
+		};
+	}
+
+	const content = await readFile(decisionsPath, 'utf-8');
+
+	// Normalize ID (handle "ADR-001", "001", or "1")
+	let searchId = id.toUpperCase();
+	if (!searchId.startsWith('ADR-')) {
+		const num = parseInt(searchId.replace(/\D/g, ''));
+		searchId = `ADR-${String(num).padStart(3, '0')}`;
+	}
+
+	// Find the decision section
+	const decisionRegex = new RegExp(
+		`## ${searchId}: ([^\\n]+)\\n\\n([\\s\\S]*?)(?=\\n## ADR-|\\n---\\n|$)`,
+		'i'
+	);
+	const match = content.match(decisionRegex);
+
+	if (!match) {
+		return {
+			content: [{ type: 'text', text: `❌ Decision ${searchId} not found in DECISIONS.md` }],
+			isError: true,
+		};
+	}
+
+	const title = match[1];
+	const body = match[2].trim();
+
+	let result = `## ${searchId}: ${title}\n\n`;
+	result += body;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
+/**
+ * Get roadmap handler
+ */
+async function getRoadmap(args) {
+	const { section } = args || {};
+	await ensureProjectDir();
+
+	const roadmapPath = join(PROJECT_DIR, 'ROADMAP.md');
+	if (!(await fileExists(roadmapPath))) {
+		return {
+			content: [
+				{
+					type: 'text',
+					text: `⚠️ ROADMAP.md not found. Use \`create_or_update_roadmap\` or \`add_roadmap_milestone\` to create it.`,
+				},
+			],
+		};
+	}
+
+	const content = await readFile(roadmapPath, 'utf-8');
+
+	if (section) {
+		// Find specific section
+		const sectionRegex = new RegExp(
+			`## [^\\n]*${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^\\n]*\\n([\\s\\S]*?)(?=\\n## |\\n---\\n|$)`,
+			'i'
+		);
+		const match = content.match(sectionRegex);
+
+		if (!match) {
+			return {
+				content: [{ type: 'text', text: `❌ Section "${section}" not found in ROADMAP.md` }],
+				isError: true,
+			};
+		}
+
+		return {
+			content: [{ type: 'text', text: match[0].trim() }],
+		};
+	}
+
+	// Return full roadmap
+	return {
+		content: [{ type: 'text', text: content }],
+	};
+}
+
 /**
  * Handler map
  */
@@ -1164,6 +1289,8 @@ export const handlers = {
 	create_or_update_decisions: createOrUpdateDecisions,
 	add_decision: addDecision,
 	list_decisions: listDecisions,
+	get_decision: getDecision,
 	update_project_status: updateProjectStatus,
 	add_roadmap_milestone: addRoadmapMilestone,
+	get_roadmap: getRoadmap,
 };

package/src/tools/tasks.js

@@ -1,6 +1,6 @@
 /**
  * Task management tools.
- * Handles: create_task, update_task, get_task, delete_task, get_next_task, list_tasks, sync_todo_index
+ * Handles: create_task, update_task, get_task, delete_task, get_next_task, list_tasks, search_tasks, sync_todo_index
  */
 
 import {
@@ -269,6 +269,40 @@ export const definitions = [
 			},
 		},
 	},
+	{
+		name: 'search_tasks',
+		description:
+			'Search tasks by keyword in title, description, or content. Returns matching tasks with relevance ranking.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				query: {
+					type: 'string',
+					description: 'Search query (matches title, description, content).',
+				},
+				project: {
+					type: 'string',
+					description: 'Filter by project.',
+				},
+				status: {
+					type: 'string',
+					description: 'Filter by status.',
+					enum: ['todo', 'in_progress', 'blocked', 'review', 'done', ''],
+				},
+				include_archived: {
+					type: 'boolean',
+					description: 'Include archived tasks in search. Default: false.',
+					default: false,
+				},
+				limit: {
+					type: 'number',
+					description: 'Maximum results to return. Default: 10.',
+					default: 10,
+				},
+			},
+			required: ['query'],
+		},
+	},
 	{
 		name: 'sync_todo_index',
 		description:
@@ -704,6 +738,88 @@ async function listTasks(args) {
 	};
 }
 
+/**
+ * Search tasks handler
+ */
+async function searchTasks(args) {
+	const { query, project, status, include_archived = false, limit = 10 } = args;
+
+	await ensureTodosDir();
+
+	// Load active tasks
+	let tasks = await loadAllTasks();
+
+	// Load archived tasks if requested
+	if (include_archived) {
+		const { ARCHIVE_DIR } = await import('../lib/constants.js');
+		const { readdir } = await import('fs/promises');
+		try {
+			const archiveFiles = await readdir(ARCHIVE_DIR);
+			for (const file of archiveFiles) {
+				if (file.endsWith('.md')) {
+					const filePath = join(ARCHIVE_DIR, file);
+					const content = await readFile(filePath, 'utf-8');
+					const parsed = matter(content);
+					tasks.push({
+						...parsed.data,
+						content: parsed.content,
+						path: `archive/${file}`,
+						archived: true,
+					});
+				}
+			}
+		} catch {
+			// Archive dir may not exist
+		}
+	}
+
+	// Apply filters
+	if (project) {
+		tasks = tasks.filter((t) => t.project === project.toUpperCase());
+	}
+	if (status) {
+		tasks = tasks.filter((t) => t.status === status);
+	}
+
+	// Search by query
+	const queryLower = query.toLowerCase();
+	const matches = tasks.filter((task) => {
+		const titleMatch = task.title?.toLowerCase().includes(queryLower);
+		const contentMatch = task.content?.toLowerCase().includes(queryLower);
+		const descMatch = task.description?.toLowerCase().includes(queryLower);
+		const tagMatch = task.tags?.some((t) => t.toLowerCase().includes(queryLower));
+		return titleMatch || contentMatch || descMatch || tagMatch;
+	});
+
+	// Sort by relevance (title matches first, then content)
+	matches.sort((a, b) => {
+		const aTitle = a.title?.toLowerCase().includes(queryLower) ? 1 : 0;
+		const bTitle = b.title?.toLowerCase().includes(queryLower) ? 1 : 0;
+		if (aTitle !== bTitle) return bTitle - aTitle;
+		return a.id.localeCompare(b.id);
+	});
+
+	const results = matches.slice(0, limit);
+
+	let result = `## Search Results: "${query}"\n\n`;
+	result += `**Found:** ${matches.length} task(s)${matches.length > limit ? ` (showing ${limit})` : ''}\n\n`;
+
+	if (results.length === 0) {
+		result += `*No tasks found matching "${query}"*\n`;
+	} else {
+		result += `| ID | Title | Status | Priority | Location |\n`;
+		result += `|----|-------|--------|----------|----------|\n`;
+		for (const task of results) {
+			const location = task.archived ? '📦 archive' : '📋 active';
+			result += `| ${task.id} | ${task.title?.substring(0, 35)}${task.title?.length > 35 ? '...' : ''} | ${task.status} | ${task.priority} | ${location} |\n`;
+		}
+	}
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
 /**
  * Sync todo index handler
  */
@@ -822,5 +938,6 @@ export const handlers = {
 	delete_task: deleteTask,
 	get_next_task: getNextTask,
 	list_tasks: listTasks,
+	search_tasks: searchTasks,
 	sync_todo_index: syncTodoIndex,
 };