project-mcp 3.2.2 → 3.2.3

package/package.json

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

@@ -14,6 +14,7 @@ export const ARCHIVE_DIR = join(PROJECT_DIR, 'archive');
 export const BACKLOG_FILE = join(PROJECT_DIR, 'BACKLOG.md');
 export const THOUGHTS_DIR = join(PROJECT_DIR, 'thoughts');
 export const THOUGHTS_TODOS_DIR = join(THOUGHTS_DIR, 'todos');
+export const THOUGHTS_ARCHIVE_DIR = join(THOUGHTS_TODOS_DIR, '.archive');
 
 /**
  * Intent to source mapping.

package/src/lib/files.js

@@ -5,7 +5,14 @@
 import { readFile, readdir, stat, writeFile, mkdir, unlink, rename } from 'fs/promises';
 import { join, extname, basename } from 'path';
 import matter from 'gray-matter';
-import { PROJECT_DIR, TODOS_DIR, ARCHIVE_DIR, THOUGHTS_DIR, THOUGHTS_TODOS_DIR } from './constants.js';
+import {
+	PROJECT_DIR,
+	TODOS_DIR,
+	ARCHIVE_DIR,
+	THOUGHTS_DIR,
+	THOUGHTS_TODOS_DIR,
+	THOUGHTS_ARCHIVE_DIR,
+} from './constants.js';
 
 /**
  * Ensure .project directory exists
@@ -62,6 +69,17 @@ export async function ensureThoughtsTodosDir() {
 	}
 }
 
+/**
+ * Ensure .project/thoughts/todos/.archive directory exists
+ */
+export async function ensureThoughtsArchiveDir() {
+	try {
+		await mkdir(THOUGHTS_ARCHIVE_DIR, { recursive: true });
+	} catch (error) {
+		// Directory might already exist
+	}
+}
+
 /**
  * Check if a file exists
  * @param {string} filePath - Path to check

package/src/tools/thoughts.js

@@ -1,17 +1,29 @@
 /**
  * Thought processing tools.
- * Handles: process_thoughts, list_thoughts, get_thought
+ * Handles: process_thoughts, list_thoughts, get_thought, archive_thought, list_archived_thoughts
  *
  * This tool reads brain dump files and provides context for the LLM to analyze.
  * The LLM does the natural language understanding - the tool just gathers data.
  */
 
 import { readdir } from 'fs/promises';
-import { THOUGHTS_TODOS_DIR, PROJECT_DIR } from '../lib/constants.js';
-import { readFile, join, fileExists, ensureThoughtsTodosDir, matter } from '../lib/files.js';
+import { THOUGHTS_TODOS_DIR, THOUGHTS_ARCHIVE_DIR } from '../lib/constants.js';
+import {
+	readFile,
+	writeFile,
+	rename,
+	join,
+	fileExists,
+	ensureThoughtsTodosDir,
+	ensureThoughtsArchiveDir,
+	matter,
+} from '../lib/files.js';
+import { getISODate, getCurrentDate } from '../lib/dates.js';
 import { loadAllTasks } from '../lib/tasks.js';
 import { loadAllFiles, getCachedFiles } from '../lib/search.js';
 
+const ARCHIVE_LOG_FILE = '.archive-log.md';
+
 /**
  * Tool definitions
  */
@@ -30,6 +42,7 @@ YOU (the LLM) should then analyze the content to:
 - 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.`,
 		inputSchema: {
@@ -48,6 +61,31 @@ The tool does NOT automatically create tasks - it provides you with everything n
 			required: ['project'],
 		},
 	},
+	{
+		name: 'archive_thought',
+		description: `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.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				file: {
+					type: 'string',
+					description: 'The thought file to archive (e.g., "my-ideas.md").',
+				},
+				created_tasks: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'Array of task IDs that were created from this thought (e.g., ["AUTH-001", "AUTH-002"]).',
+				},
+				notes: {
+					type: 'string',
+					description: 'Optional notes about the processing (e.g., "Consolidated 5 items into 2 tasks").',
+				},
+			},
+			required: ['file'],
+		},
+	},
 	{
 		name: 'list_thoughts',
 		description:
@@ -60,6 +98,26 @@ The tool does NOT automatically create tasks - it provides you with everything n
 					description: 'Optional: Filter by thought category. Currently supported: "todos".',
 					enum: ['todos', ''],
 				},
+				include_archived: {
+					type: 'boolean',
+					description: 'Include archived thoughts in the listing. Default: false.',
+					default: false,
+				},
+			},
+		},
+	},
+	{
+		name: 'list_archived_thoughts',
+		description:
+			'Lists all archived thought files with their processing history. Shows what thoughts were processed, when, and what tasks were created.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				limit: {
+					type: 'number',
+					description: 'Maximum number of archived thoughts to show. Default: 20.',
+					default: 20,
+				},
 			},
 		},
 	},
@@ -78,6 +136,11 @@ The tool does NOT automatically create tasks - it provides you with everything n
 					description: 'The category/subdirectory. Default: "todos".',
 					default: 'todos',
 				},
+				from_archive: {
+					type: 'boolean',
+					description: 'Read from archive instead of active thoughts. Default: false.',
+					default: false,
+				},
 			},
 			required: ['file'],
 		},
@@ -113,7 +176,7 @@ async function getProjectContext() {
 		// Get roadmap content
 		const roadmapFile = files.find(f => f.path.includes('ROADMAP'));
 		if (roadmapFile) {
-			context.roadmap = roadmapFile.content.substring(0, 2000); // First 2000 chars
+			context.roadmap = roadmapFile.content.substring(0, 2000);
 		}
 
 		// Get decisions
@@ -126,7 +189,7 @@ async function getProjectContext() {
 		// Get current status
 		const statusFile = files.find(f => f.path.includes('STATUS'));
 		if (statusFile) {
-			context.status = statusFile.content.substring(0, 1000); // First 1000 chars
+			context.status = statusFile.content.substring(0, 1000);
 		}
 	} catch {
 		// Context loading failed, continue without it
@@ -163,7 +226,7 @@ async function processThoughts(args) {
 		try {
 			const files = await readdir(THOUGHTS_TODOS_DIR);
 			filesToProcess = files
-				.filter(f => f.endsWith('.md'))
+				.filter(f => f.endsWith('.md') && !f.startsWith('.'))
 				.map(f => ({ name: f, path: join(THOUGHTS_TODOS_DIR, f) }));
 		} catch {
 			// Directory might not exist yet
@@ -227,6 +290,10 @@ Analyze the thought content below and create appropriate tasks. Consider:
    - tags: Relevant categorization
    - subtasks: Array of subtask strings (for consolidated items)
 
+5. **After creating tasks, archive the thought file** using \`archive_thought\`:
+   - Pass the filename and array of created task IDs
+   - This keeps the thoughts folder clean and maintains a processing log
+
 ---
 
 ## Thought Files to Process
@@ -275,6 +342,7 @@ Use this to understand what already exists and align new tasks appropriately.
 		}
 	}
 
+	const filenames = thoughtContents.map(t => t.filename).join('", "');
 	result += `
 ---
 
@@ -285,6 +353,10 @@ Now analyze the thought content above and:
 1. Identify the distinct tasks/initiatives (consolidate related items)
 2. For each task, determine title, priority, and relevant context
 3. Use \`create_task\` to create well-structured tasks
+4. **After creating tasks, use \`archive_thought\`** to archive each processed file:
+   \`\`\`
+   archive_thought(file: "${thoughtContents[0]?.filename || 'filename.md'}", created_tasks: ["${project.toUpperCase()}-001", ...])
+   \`\`\`
 
 Remember: Quality over quantity. Create fewer, well-scoped tasks rather than many granular ones.
 `;
@@ -294,11 +366,171 @@ Remember: Quality over quantity. Create fewer, well-scoped tasks rather than man
 	};
 }
 
+/**
+ * Archive thought handler
+ */
+async function archiveThought(args) {
+	const { file, created_tasks = [], notes } = args;
+
+	await ensureThoughtsTodosDir();
+	await ensureThoughtsArchiveDir();
+
+	const sourcePath = join(THOUGHTS_TODOS_DIR, file);
+	const archivePath = join(THOUGHTS_ARCHIVE_DIR, file);
+	const logPath = join(THOUGHTS_ARCHIVE_DIR, ARCHIVE_LOG_FILE);
+
+	// Check if file exists
+	if (!(await fileExists(sourcePath))) {
+		return {
+			content: [
+				{
+					type: 'text',
+					text: `❌ File not found: ${file}\n\nUse \`list_thoughts\` to see available files.`,
+				},
+			],
+			isError: true,
+		};
+	}
+
+	// Read the original content for the log
+	const originalContent = await readFile(sourcePath, 'utf-8');
+	const lineCount = originalContent.split('\n').length;
+
+	// Move file to archive
+	await rename(sourcePath, archivePath);
+
+	// Update archive log
+	let logContent = '';
+	try {
+		if (await fileExists(logPath)) {
+			logContent = await readFile(logPath, 'utf-8');
+		}
+	} catch {
+		// Log file doesn't exist yet
+	}
+
+	// Create log entry
+	const logEntry = `
+## ${file}
+
+**Archived:** ${getCurrentDate()}
+**Original Lines:** ${lineCount}
+**Tasks Created:** ${created_tasks.length > 0 ? created_tasks.join(', ') : 'None specified'}
+${notes ? `**Notes:** ${notes}` : ''}
+
+---
+`;
+
+	// Prepend new entry to log (newest first)
+	if (!logContent.includes('# Thought Archive Log')) {
+		logContent = `# Thought Archive Log
+
+This file tracks all processed thoughts and the tasks created from them.
+
+---
+${logEntry}`;
+	} else {
+		logContent = logContent.replace(
+			'---\n',
+			`---
+${logEntry}`
+		);
+	}
+
+	await writeFile(logPath, logContent, 'utf-8');
+
+	let result = `## Thought Archived: ${file}\n\n`;
+	result += `**Moved to:** \`.project/thoughts/todos/.archive/${file}\`\n`;
+	result += `**Archived:** ${getCurrentDate()}\n`;
+	result += `**Lines:** ${lineCount}\n`;
+
+	if (created_tasks.length > 0) {
+		result += `\n**Tasks Created:**\n`;
+		for (const taskId of created_tasks) {
+			result += `- ${taskId}\n`;
+		}
+	}
+
+	if (notes) {
+		result += `\n**Notes:** ${notes}\n`;
+	}
+
+	result += `\n✅ Thought file archived successfully. Use \`list_archived_thoughts\` to see archive history.`;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
+/**
+ * List archived thoughts handler
+ */
+async function listArchivedThoughts(args) {
+	const { limit = 20 } = args || {};
+
+	await ensureThoughtsArchiveDir();
+
+	let result = `## Archived Thoughts\n\n`;
+	result += `**Path:** \`.project/thoughts/todos/.archive/\`\n\n`;
+
+	// Read archive log if exists
+	const logPath = join(THOUGHTS_ARCHIVE_DIR, ARCHIVE_LOG_FILE);
+	let logContent = '';
+
+	try {
+		if (await fileExists(logPath)) {
+			logContent = await readFile(logPath, 'utf-8');
+		}
+	} catch {
+		// Log doesn't exist
+	}
+
+	if (logContent) {
+		result += `### Archive Log\n\n`;
+		// Show the log content (it's already formatted)
+		const entries = logContent.split('## ').slice(1, limit + 1);
+		for (const entry of entries) {
+			result += `## ${entry}\n`;
+		}
+	}
+
+	// Also list actual files in archive
+	try {
+		const files = await readdir(THOUGHTS_ARCHIVE_DIR);
+		const mdFiles = files.filter(f => f.endsWith('.md') && f !== ARCHIVE_LOG_FILE);
+
+		if (mdFiles.length > 0) {
+			result += `\n### Archived Files (${mdFiles.length})\n\n`;
+			result += `| File | Size |\n`;
+			result += `|------|------|\n`;
+			for (const file of mdFiles.slice(0, limit)) {
+				const filePath = join(THOUGHTS_ARCHIVE_DIR, file);
+				const content = await readFile(filePath, 'utf-8');
+				const lines = content.split('\n').length;
+				result += `| ${file} | ${lines} lines |\n`;
+			}
+		}
+	} catch {
+		// Archive directory might not exist
+	}
+
+	if (!logContent && result.includes('Archived Files') === false) {
+		result += `*No archived thoughts yet. Use \`archive_thought\` after processing thoughts.*\n`;
+	}
+
+	result += `\n---\n`;
+	result += `**Tools:** \`get_thought\` with \`from_archive: true\` to read archived files`;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
 /**
  * List thoughts handler
  */
 async function listThoughts(args) {
-	const { category } = args || {};
+	const { category, include_archived = false } = args || {};
 
 	await ensureThoughtsTodosDir();
 
@@ -311,7 +543,7 @@ async function listThoughts(args) {
 		try {
 			if (await fileExists(catDir)) {
 				const files = await readdir(catDir);
-				const mdFiles = files.filter(f => f.endsWith('.md'));
+				const mdFiles = files.filter(f => f.endsWith('.md') && !f.startsWith('.'));
 
 				results[cat] = [];
 				for (const file of mdFiles) {
@@ -353,9 +585,24 @@ async function listThoughts(args) {
 		}
 	}
 
+	// Show archived count if requested
+	if (include_archived) {
+		try {
+			await ensureThoughtsArchiveDir();
+			const archivedFiles = await readdir(THOUGHTS_ARCHIVE_DIR);
+			const archivedMd = archivedFiles.filter(f => f.endsWith('.md') && f !== ARCHIVE_LOG_FILE);
+			if (archivedMd.length > 0) {
+				result += `### 📦 .archive/ (${archivedMd.length} files)\n\n`;
+				result += `Use \`list_archived_thoughts\` to see details.\n\n`;
+			}
+		} catch {
+			// Archive doesn't exist
+		}
+	}
+
 	result += `---\n`;
-	result += `**Total files:** ${totalFiles}\n\n`;
-	result += `**Tools:** \`get_thought\` to read | \`process_thoughts\` to analyze`;
+	result += `**Total active files:** ${totalFiles}\n\n`;
+	result += `**Tools:** \`get_thought\` to read | \`process_thoughts\` to analyze | \`archive_thought\` after processing`;
 
 	return {
 		content: [{ type: 'text', text: result }],
@@ -366,19 +613,27 @@ async function listThoughts(args) {
  * Get thought handler
  */
 async function getThought(args) {
-	const { file, category = 'todos' } = args;
+	const { file, category = 'todos', from_archive = false } = args;
 
 	await ensureThoughtsTodosDir();
 
-	const catDir = category === 'todos' ? THOUGHTS_TODOS_DIR : join(THOUGHTS_TODOS_DIR, '..', category);
+	let catDir;
+	if (from_archive) {
+		await ensureThoughtsArchiveDir();
+		catDir = THOUGHTS_ARCHIVE_DIR;
+	} else {
+		catDir = category === 'todos' ? THOUGHTS_TODOS_DIR : join(THOUGHTS_TODOS_DIR, '..', category);
+	}
+
 	const filePath = join(catDir, file);
 
 	if (!(await fileExists(filePath))) {
+		const location = from_archive ? '.archive' : category;
 		return {
 			content: [
 				{
 					type: 'text',
-					text: `❌ File not found: \`.project/thoughts/${category}/${file}\`\n\nUse \`list_thoughts\` to see available files.`,
+					text: `❌ File not found: \`.project/thoughts/todos/${location}/${file}\`\n\nUse \`list_thoughts\` or \`list_archived_thoughts\` to see available files.`,
 				},
 			],
 			isError: true,
@@ -388,9 +643,10 @@ async function getThought(args) {
 	const content = await readFile(filePath, 'utf-8');
 	const parsed = matter(content);
 
+	const location = from_archive ? 'todos/.archive' : category;
 	let result = `## Thought File: ${file}\n\n`;
-	result += `**Path:** \`.project/thoughts/${category}/${file}\`\n`;
-	result += `**Category:** ${category}\n\n`;
+	result += `**Path:** \`.project/thoughts/${location}/${file}\`\n`;
+	result += `**Status:** ${from_archive ? '📦 Archived' : '📝 Active'}\n\n`;
 
 	if (Object.keys(parsed.data).length > 0) {
 		result += `### Frontmatter\n\n`;
@@ -405,7 +661,11 @@ async function getThought(args) {
 	result += parsed.content;
 
 	result += `\n\n---\n`;
-	result += `**Tools:** \`process_thoughts\` to analyze and create tasks`;
+	if (from_archive) {
+		result += `**This file has been archived.** It was already processed into tasks.`;
+	} else {
+		result += `**Tools:** \`process_thoughts\` to analyze | \`archive_thought\` after creating tasks`;
+	}
 
 	return {
 		content: [{ type: 'text', text: result }],
@@ -417,6 +677,8 @@ async function getThought(args) {
  */
 export const handlers = {
 	process_thoughts: processThoughts,
+	archive_thought: archiveThought,
 	list_thoughts: listThoughts,
+	list_archived_thoughts: listArchivedThoughts,
 	get_thought: getThought,
 };