project-mcp 3.2.3 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "project-mcp",
-	"version": "3.2.3",
+	"version": "3.3.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/lib/constants.js

@@ -19,15 +19,24 @@ export const THOUGHTS_ARCHIVE_DIR = join(THOUGHTS_TODOS_DIR, '.archive');
 /**
  * Intent to source mapping.
  * Maps user intent to which directories should be searched.
+ *
+ * IMPORTANT DISTINCTION:
+ * - "project" (operational) → .project/ management files (status, todos, roadmap, backlog)
+ * - "project_docs" (documentation) → docs/ folder + DECISIONS.md (application documentation)
+ *
+ * When users say "project docs" or "project documentation", they mean APPLICATION
+ * documentation (how the system works), NOT project management (tracking work).
  */
 export const INTENT_SOURCES = {
 	project: ['project', 'root', 'docs'], // .project/, root files, docs/
 	docs: ['docs'], // Only docs/
+	project_docs: ['docs', 'decisions'], // Application documentation: docs/ + DECISIONS.md
 	plan: ['project'], // Only .project/
 	todos: ['project'],
 	roadmap: ['project'],
 	status: ['project'],
 	operational: ['project'],
+	decisions: ['decisions'], // Architecture decisions only (DECISIONS.md)
 };
 
 /**

package/src/lib/search.js

@@ -31,12 +31,28 @@ export function detectIntent(query, explicitIntent) {
 
 	const queryLower = query.toLowerCase();
 
-	// Check for operational keywords
-	if (/\b(plan|plans|todo|todos|roadmap|status|operational|current state|decisions)\b/.test(queryLower)) {
+	// Check for "project docs/documents/documentation" - this means APPLICATION documentation
+	// NOT project management. Routes to docs/ folder + DECISIONS.md
+	if (
+		/\b(project\s+doc(s|ument(s|ation)?)?|update\s+(project\s+)?doc(s|ument(s|ation)?)?|application\s+doc(s|ument(s|ation)?)?)\b/.test(
+			queryLower
+		)
+	) {
+		return 'project_docs';
+	}
+
+	// Check for architecture decisions specifically
+	if (/\b(decision(s)?|adr|architecture\s+decision(s)?|technical\s+decision(s)?)\b/.test(queryLower)) {
+		return 'decisions';
+	}
+
+	// Check for operational/project management keywords (status, todos, roadmap, backlog)
+	// This is DIFFERENT from "project docs" - this is about tracking work, not documenting the system
+	if (/\b(plan|plans|todo|todos|roadmap|status|operational|current state|backlog)\b/.test(queryLower)) {
 		return 'plan';
 	}
 
-	// Check for docs-specific keywords
+	// Check for docs-only keywords (just "docs" or "documentation" without "project")
 	if (/\b(docs|documentation|reference|guide|guides|api docs)\b/.test(queryLower)) {
 		return 'docs';
 	}
@@ -51,7 +67,12 @@ export function detectIntent(query, explicitIntent) {
  * @returns {string[]} Array of source names
  */
 export function getSourcesForIntent(intent) {
-	return INTENT_SOURCES[intent] || INTENT_SOURCES.project;
+	const sources = INTENT_SOURCES[intent] || INTENT_SOURCES.project;
+
+	// 'decisions' is a virtual source that maps to DECISIONS.md in .project/
+	// When we see 'decisions' in the sources, we need to include it for filtering
+	// The actual loading happens in loadAllFiles() which tags DECISIONS.md with source='decisions'
+	return sources;
 }
 
 /**
@@ -67,8 +88,21 @@ export async function loadAllFiles(force = false) {
 	const allFiles = [];
 
 	// Load .project/ directory
+	// DECISIONS.md gets special treatment - it's tagged as both 'project' and 'decisions'
+	// because it's application documentation (explains WHY the system is built this way)
+	// not just project management
 	try {
-		await scanDirectory(PROJECT_DIR, '.project', allFiles, 'project');
+		const projectFiles = [];
+		await scanDirectory(PROJECT_DIR, '.project', projectFiles, 'project');
+
+		// Tag DECISIONS.md with source='decisions' so it appears in project_docs queries
+		for (const file of projectFiles) {
+			if (file.path.endsWith('DECISIONS.md')) {
+				// DECISIONS.md is application documentation, not just project management
+				file.source = 'decisions';
+			}
+			allFiles.push(file);
+		}
 	} catch (error) {
 		// .project/ might not exist
 	}

package/src/prompts/definitions.js

@@ -24,6 +24,7 @@ export const promptToolMapping = {
 	get_backlog: ['get_backlog'],
 	add_decision: ['add_decision'],
 	update_status: ['update_project_status'],
+	update_project_docs: ['search_project', 'get_doc', 'add_decision', 'list_docs'],
 };
 
 /**
@@ -204,6 +205,25 @@ export const prompts = [
 			},
 		],
 	},
+	{
+		name: 'update_project_docs',
+		description:
+			'Update project documentation - the APPLICATION documentation that explains how the system works. Use when user says "update project docs", "update project documents", "update project documentation", "update application docs", or "document this". This is DIFFERENT from project management (status, todos, roadmap) - this updates the docs/ folder and DECISIONS.md which contain reference documentation about the application itself.',
+		arguments: [
+			{
+				name: 'content',
+				description:
+					'What to document or update. The model will determine whether this belongs in docs/ (application documentation) or DECISIONS.md (architecture decisions).',
+				required: true,
+			},
+			{
+				name: 'doc_type',
+				description:
+					'Hint for documentation type: "decision" for architecture decisions (DECISIONS.md), "release" for release notes, "guide" for user guides, "api" for API docs, or "auto" to let the model decide based on content.',
+				required: false,
+			},
+		],
+	},
 ];
 
 /**

package/src/prompts/index.js

@@ -203,6 +203,32 @@ This adds a timestamped status entry to STATUS.md.`,
 				},
 			},
 		],
+		update_project_docs: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: `Update project documentation with: "${args.content || '[CONTENT]'}".
+
+IMPORTANT: This is about APPLICATION DOCUMENTATION (how the system works), NOT project management (status, todos, roadmap).
+
+${args.doc_type === 'decision' ? `This is an architecture decision. Use the \`add_decision\` tool to add it to DECISIONS.md.` : args.doc_type === 'release' ? `This is a release note. Look in docs/releases/ and update the appropriate file.` : `Based on the content, determine where this documentation belongs:
+
+1. **Architecture Decision?** (design choice, trade-off, technical rationale)
+   → Use \`add_decision\` tool to add to DECISIONS.md
+
+2. **Application Documentation?** (how-to, API docs, guides, reference)
+   → First use \`search_project\` with intent "project_docs" to find relevant existing docs
+   → Then use \`list_docs\` to see the docs/ structure
+   → Update the appropriate file in docs/
+
+3. **Release Notes?** (version changes, features, fixes)
+   → Check docs/releases/ for the right file
+
+The model decides where this content best fits based on its nature.`}`,
+				},
+			},
+		],
 	};
 
 	return (
@@ -236,6 +262,7 @@ export function getMessageHandlerKeys() {
 		get_backlog: true,
 		add_decision: true,
 		update_status: true,
+		update_project_docs: true,
 	};
 	return Object.keys(messages);
 }

package/src/tools/lint.js

@@ -378,42 +378,52 @@ ${project_description}
 
 ## Contract for AI Agents
 
-When a user says **"project"**, **"the project"**, or **"my project"**, the canonical sources of truth are:
+### Critical Distinction: Project Management vs Project Documentation
 
-1. **\`.project/\`** — Current state, plans, todos, decisions (operational truth)
-2. **Root markdown files** — README.md, CONTRIBUTING.md, etc.
-3. **\`docs/\`** — Long-form reference documentation
+| Term | Means | Sources |
+|------|-------|---------|
+| **"project docs"** / **"project documentation"** | Application documentation (HOW the system works) | \`docs/\` + \`DECISIONS.md\` |
+| **"project status"** / **"todos"** / **"roadmap"** | Project management (WHAT we're doing) | \`.project/\` management files |
+
+**DECISIONS.md is special**: It's application documentation (explains WHY decisions were made) even though it lives in \`.project/\`.
 
 ## Source Mappings
 
-### "project" / "the project"
-Searches: \`.project/\` + root files + \`docs/\`
+### "project docs" / "project documents" / "project documentation"
+APPLICATION documentation — how the system works, why it was built this way.
+Searches: \`docs/\` + \`DECISIONS.md\`
 
-### "docs" / "documentation"
+### "docs" / "documentation" / "reference"
+Reference documentation only.
 Searches: \`docs/\` only
 
-### "plan" / "todos" / "roadmap" / "status"
-Searches: \`.project/\` only
+### "plan" / "todos" / "roadmap" / "status" / "backlog"
+Project MANAGEMENT — tracking work, not documenting the system.
+Searches: \`.project/\` (excluding DECISIONS.md)
+
+### "project" / "the project"
+Everything (when intent is ambiguous).
+Searches: \`.project/\` + root files + \`docs/\`
 
 ## File Structure
 
-| File | Purpose |
-|------|---------|
-| \`index.md\` | This file - contract and source mappings |
-| \`BACKLOG.md\` | Prioritized work queue (future tasks) |
-| \`TODO.md\` | Task dashboard (active work, auto-generated) |
-| \`ROADMAP.md\` | Project phases and milestones |
-| \`STATUS.md\` | Current project health and progress |
-| \`DECISIONS.md\` | Architecture decisions and rationale |
-| \`todos/\` | Active task files (10-30 items, not hundreds) |
-| \`archive/\` | Completed tasks (for history) |
+| File | Type | Purpose |
+|------|------|---------|
+| \`index.md\` | Contract | This file - source mappings |
+| \`DECISIONS.md\` | **Documentation** | Architecture decisions (WHY) |
+| \`BACKLOG.md\` | Management | Prioritized work queue |
+| \`TODO.md\` | Management | Task dashboard |
+| \`ROADMAP.md\` | Management | Project phases/milestones |
+| \`STATUS.md\` | Management | Project health/progress |
+| \`todos/\` | Management | Active task files |
+| \`archive/\` | Management | Completed tasks |
 
 ## Principles
 
-- **Natural language stays natural** — Users say "project" not ".project/"
+- **"Project docs" ≠ "Project management"** — Users saying "update project docs" want application documentation updated, not task tracking
+- **DECISIONS.md is documentation** — It explains the system, not tracks work
+- **Natural language stays natural** — "Project docs" maps to docs/ + DECISIONS.md
 - **Agents don't guess** — Explicit mappings defined here
-- **Intent over structure** — Language maps to intent, not directory names
-- **Operational truth** — This directory is the source of truth for current state
 
 ---
 *Last Updated: ${date}*

package/src/tools/search.js

@@ -16,7 +16,7 @@ export const definitions = [
 	{
 		name: 'search_project',
 		description:
-			'Search across all project sources: .project/ (operational truth), root-level files, and docs/ (reference truth). Use this when the user says "project", "the project", or asks about project status, plans, todos, or roadmap. Maps natural language to appropriate sources automatically.',
+			'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).',
 		inputSchema: {
 			type: 'object',
 			properties: {
@@ -28,8 +28,19 @@ export const definitions = [
 				intent: {
 					type: 'string',
 					description:
-						'Optional: Intent type to map to sources. Options: "project" (searches .project/, root, docs), "docs" (only docs/), "plan/todos/roadmap/status/operational" (only .project/). If not specified, automatically detects from query.',
-					enum: ['project', 'docs', 'plan', 'todos', 'roadmap', 'status', 'operational', ''],
+						'Intent type to map to sources. "project_docs" searches docs/ + DECISIONS.md (application documentation). "docs" searches only docs/. "plan/todos/roadmap/status/operational" searches .project/ (project management). "project" searches everything. "decisions" searches only DECISIONS.md.',
+					enum: [
+						'project',
+						'project_docs',
+						'docs',
+						'decisions',
+						'plan',
+						'todos',
+						'roadmap',
+						'status',
+						'operational',
+						'',
+					],
 				},
 				maxResults: {
 					type: 'number',