ai-prompt-guide-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Blake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# AI Prompt Guide MCP
+
+**MCP Server & Claude Code Plugin for Multi-Agent Workflows**
+
+An MCP server that orchestrates AI agents through structured markdown documents. Create linked specifications and tasks, assign work to specialized agents with a single command, and let the system handle context injection and workflow management automatically.
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Key Features](#key-features)
+- [Getting Started](#getting-started)
+- [Claude Code Plugin](#claude-code-plugin)
+- [Tools Overview](#tools-overview)
+- [Use Case](#use-case)
+- [License](#license)
+
+## What It Does
+
+This server enables you to:
+
+- **Spec out projects** as a team or solo using interlinked markdown documents
+- **Make better decisions** using the multi-option tradeoff workflow
+- **Orchestrate specialized agents** by simply assigning tasks—the server injects the right context automatically
+- **Maintain impartial reviews** by keeping the coordinator agent separate from implementation details
+
+### How It Works
+
+1. **Create linked documents** with specifications, guides, and architecture decisions
+2. **Add @references** to link related content that gets auto-injected when needed
+3. **Assign tasks to agents** using coordinator or subagent workflows
+4. **Agent completes and reports** "Done"—coordinator reviews code changes directly
+5. **Review without bias** by examining the actual changes, only consulting notes if needed
+
+The system preserves context across sessions while keeping your main agent focused on orchestration and review rather than implementation details.
+
+## Key Features
+
+**Dual Task System**
+- **Coordinator tasks** for sequential project work (auto-archives when complete)
+- **Subagent tasks** for flexible ad-hoc work across documents
+
+**Automatic Context Injection**
+- Link documents with `@/path/doc.md#section` syntax
+- Referenced content loads automatically when tasks start
+- Works on any project—no configuration needed
+
+**Workflow Library**
+- 11 pre-built workflows for common development scenarios
+- Access via `get_workflow` tool or Claude Code plugin commands
+- Reference workflows in task metadata for automatic injection
+- Create your own custom workflows easily
+
+## Getting Started
+
+### Requirements
+
+- Node.js 18+
+- pnpm 10.x
+
+### Install & Build
+
+```bash
+pnpm install
+pnpm build
+```
+
+### Run the Server
+
+```bash
+# Development
+pnpm dev
+
+# Production
+pnpm start
+
+# Test with inspector
+pnpm inspector
+```
+
+### Configuration
+
+**Zero-config by default** - the server works immediately with no setup required. When you run Claude Code from a project directory, it automatically creates a `.ai-prompt-guide/` folder in your project to store documents, tasks, and archives.
+
+**Optional configuration** for custom paths:
+
+```json
+{
+  "mcpServers": {
+    "ai-prompt-guide-mcp": {
+      "command": "npx",
+      "args": ["-y", "ai-prompt-guide-mcp"],
+      "env": {
+        "MCP_WORKSPACE_PATH": "/custom/workspace/path"
+      }
+    }
+  }
+}
+```
+
+**Optional Settings:**
+
+- `MCP_WORKSPACE_PATH` - Custom workspace path (default: current directory)
+- `DOCS_BASE_PATH` - Documents location (default: `.ai-prompt-guide/docs` in zero-config mode)
+- `ARCHIVED_BASE_PATH` - Archived documents (default: `.ai-prompt-guide/archived` in zero-config mode)
+- `COORDINATOR_BASE_PATH` - Coordinator tasks (default: `.ai-prompt-guide/coordinator` in zero-config mode)
+- `REFERENCE_EXTRACTION_DEPTH` - How deep to follow @references (1-5, default: 3)
+- `LOG_LEVEL` - Logging verbosity (debug, info, warn, error)
+
+**Per-Project Configuration:**
+
+Create `.mcp-config.json` in your project root for project-specific settings:
+
+```json
+{
+  "env": {
+    "DOCS_BASE_PATH": "/custom/docs",
+    "ARCHIVED_BASE_PATH": "/custom/archive",
+    "COORDINATOR_BASE_PATH": "/custom/coordinator"
+  }
+}
+```
+
+### Directory Structure
+
+**Zero-config structure** (created automatically in your project):
+
+```
+your-project/
+└── .ai-prompt-guide/
+    ├── docs/               # Your documents and subagent tasks
+    ├── coordinator/        # Sequential project tasks
+    └── archived/           # Completed work (auto-populated)
+        ├── docs/           # Archived documents
+        └── coordinator/    # Archived task lists
+```
+
+**Shared resources** (bundled with the MCP server):
+
+```
+{mcp-server}/.ai-prompt-guide/
+├── workflows/         # Reusable workflow protocols
+└── guides/           # Documentation best practices
+```
+
+Everything is created automatically—no manual setup required. Workflows and guides are shared across all your projects.
+
+## Claude Code Plugin
+
+### Install
+
+```bash
+/plugin marketplace add https://github.com/Blakeem/AI-Prompt-Guide-MCP
+/plugin install ai-prompt-guide
+```
+
+### Workflows & Commands
+
+The plugin provides **11 workflows** accessible both as slash commands and via the `get_workflow` MCP tool:
+
+**Development Workflows:**
+- `/ai-prompt-guide:develop` – Simple development with anti-pattern detection and regression prevention
+- `/ai-prompt-guide:develop-fix` – Bug fixing with root cause analysis and regression prevention
+- `/ai-prompt-guide:develop-tdd` – Orchestrate multi-agent development with TDD
+- `/ai-prompt-guide:develop-iterate` – Orchestrate multi-agent development with manual verification
+
+**Quality & Review Workflows:**
+- `/ai-prompt-guide:review` – Targeted review of PRs or components
+- `/ai-prompt-guide:audit` – Quality audit with specialized agents
+- `/ai-prompt-guide:coverage` – Add comprehensive test coverage
+
+**Decision Workflows:**
+- `/ai-prompt-guide:decide` – Structured decision making with trade-off analysis
+- `/ai-prompt-guide:decide-iterate` – Multi-perspective decision analysis with parallel agents
+
+**Specification Workflows:**
+- `/ai-prompt-guide:spec-feature` – Document internal feature specifications
+- `/ai-prompt-guide:spec-external` – Document external API specifications
+
+**Commands are shortcuts to workflows.** When using Claude Code, the plugin commands provide a convenient way to invoke workflows. When using the MCP server directly, access the same workflows via:
+
+```typescript
+get_workflow({ workflow: "develop" })
+get_workflow({ workflow: "develop-fix" })
+get_workflow({ workflow: "develop-tdd" })
+get_workflow({ workflow: "audit" })
+// ... etc
+```
+
+### Examples
+
+**Simple development (no multi-agent orchestration):**
+```
+/ai-prompt-guide:develop Add a dark mode toggle to the settings page with persistence to localStorage
+```
+
+**Bug fixing:**
+```
+/ai-prompt-guide:develop-fix The form submission fails when the email field is empty - returns undefined instead of validation error
+```
+
+**Multi-agent development with TDD:**
+```
+/ai-prompt-guide:develop-tdd Build an admin dashboard with user activity charts, region filtering, and CSV export. Include tests for the aggregation logic.
+```
+
+The plugin loads the appropriate workflow and guides you through the implementation process.
+
+## Tools Overview
+
+The server provides 20 MCP tools organized by function:
+
+### Document Discovery & Navigation
+
+- **`create_document`** – Create new documents with namespace selection
+- **`browse_documents`** – Navigate document hierarchy and list contents
+- **`search_documents`** – Full-text or regex search across all documents
+
+### Content Editing
+
+- **`section`** – Edit, append, insert, or remove sections in bulk
+
+### Coordinator Task Management
+
+- **`coordinator_task`** – Create, edit, or list coordinator tasks
+- **`start_coordinator_task`** – Start the first pending task with full context
+- **`complete_coordinator_task`** – Complete task and get next or auto-archive
+- **`view_coordinator_task`** – View coordinator task details
+
+### Subagent Task Management
+
+- **`subagent_task`** – Create, edit, or list subagent tasks
+- **`start_subagent_task`** – Start specific task with full context
+- **`complete_subagent_task`** – Complete task and get next pending
+- **`view_subagent_task`** – View subagent task details
+
+### View & Inspection
+
+- **`view_document`** – View complete document structure with metadata
+- **`view_section`** – View section content without starting work
+
+### Document Lifecycle
+
+- **`edit_document`** – Update document title and overview
+- **`delete_document`** – Delete or archive documents
+- **`move`** – Move sections within or across documents (supports both regular sections and subagent tasks)
+- **`move_document`** – Move documents to new namespaces
+
+### Workflow & Guide Access
+
+- **`get_workflow`** – Load workflow protocol content
+- **`get_guide`** – Access documentation guides
+
+All tools use consistent addressing (`/doc.md#section`) and work together seamlessly.
+
+## Use Case
+
+**Spec-driven development with automatic agent orchestration:**
+
+1. Create linked specification documents for your project
+2. Add coordinator tasks for the implementation phases
+3. Assign the first task to a specialized agent with one command
+4. Agent gets full context automatically (specs, workflows, references)
+5. Agent completes work and reports "Done"
+6. Review actual code changes to maintain objectivity
+7. Move to next task—system queues it with the right context
+
+The coordinator agent stays focused on orchestration and quality while specialized agents handle implementation. Your impartiality is preserved because you review code directly, not summaries.
+
+## License
+
+MIT. See `LICENSE` for details.

package/dist/__tests__/config-loading.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for .mcp-config.json loading functionality
+ */
+export {};
+//# sourceMappingURL=config-loading.test.d.ts.map

package/dist/__tests__/config-loading.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loading.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config-loading.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/config-loading.test.js

@@ -0,0 +1,127 @@
+/**
+ * Tests for .mcp-config.json loading functionality
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { loadProjectConfig } from '../config.js';
+import { getGlobalLogger, setGlobalLogger, createSilentLogger } from '../utils/logger.js';
+describe('loadProjectConfig', () => {
+    let testDir;
+    let originalCwd;
+    let originalLogger;
+    beforeEach(() => {
+        // Create a temporary directory for test files
+        testDir = join(tmpdir(), `mcp-config-test-${Date.now()}`);
+        mkdirSync(testDir, { recursive: true });
+        // Save original cwd and change to test directory
+        originalCwd = process.cwd();
+        process.chdir(testDir);
+        // Save original logger and set silent logger for tests
+        originalLogger = getGlobalLogger();
+        setGlobalLogger(createSilentLogger());
+    });
+    afterEach(() => {
+        // Restore original cwd
+        process.chdir(originalCwd);
+        // Clean up test directory
+        try {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        // Restore original logger
+        setGlobalLogger(originalLogger);
+    });
+    it('returns empty object when .mcp-config.json does not exist', () => {
+        const result = loadProjectConfig();
+        expect(result).toEqual({});
+    });
+    it('returns parsed config when valid JSON with correct structure', () => {
+        const config = {
+            env: {
+                MCP_WORKSPACE_PATH: '/custom/docs',
+                WORKFLOWS_BASE_PATH: '/custom/workflows',
+                GUIDES_BASE_PATH: '/custom/guides'
+            }
+        };
+        writeFileSync(join(testDir, '.mcp-config.json'), JSON.stringify(config));
+        const result = loadProjectConfig();
+        expect(result).toEqual(config.env);
+    });
+    it('returns empty object and logs warning when JSON is invalid', () => {
+        let loggedWarning = false;
+        const mockLogger = {
+            error: () => { },
+            warn: () => { loggedWarning = true; },
+            info: () => { },
+            debug: () => { }
+        };
+        setGlobalLogger(mockLogger);
+        writeFileSync(join(testDir, '.mcp-config.json'), '{ invalid json }');
+        const result = loadProjectConfig();
+        expect(result).toEqual({});
+        expect(loggedWarning).toBe(true);
+    });
+    it('returns empty object and logs warning when structure is invalid (missing env)', () => {
+        let loggedWarning = false;
+        const mockLogger = {
+            error: () => { },
+            warn: () => { loggedWarning = true; },
+            info: () => { },
+            debug: () => { }
+        };
+        setGlobalLogger(mockLogger);
+        const invalidConfig = {
+            notEnv: {
+                MCP_WORKSPACE_PATH: '/custom/docs'
+            }
+        };
+        writeFileSync(join(testDir, '.mcp-config.json'), JSON.stringify(invalidConfig));
+        const result = loadProjectConfig();
+        expect(result).toEqual({});
+        expect(loggedWarning).toBe(true);
+    });
+    it('returns empty object and logs warning when env is not an object', () => {
+        let loggedWarning = false;
+        const mockLogger = {
+            error: () => { },
+            warn: () => { loggedWarning = true; },
+            info: () => { },
+            debug: () => { }
+        };
+        setGlobalLogger(mockLogger);
+        const invalidConfig = {
+            env: 'not an object'
+        };
+        writeFileSync(join(testDir, '.mcp-config.json'), JSON.stringify(invalidConfig));
+        const result = loadProjectConfig();
+        expect(result).toEqual({});
+        expect(loggedWarning).toBe(true);
+    });
+    it('returns empty object and logs warning when env field has invalid type', () => {
+        let loggedWarning = false;
+        const mockLogger = {
+            error: () => { },
+            warn: () => { loggedWarning = true; },
+            info: () => { },
+            debug: () => { }
+        };
+        setGlobalLogger(mockLogger);
+        const config = {
+            env: {
+                MCP_WORKSPACE_PATH: '/custom/docs',
+                WORKFLOWS_BASE_PATH: 123, // Invalid: should be string
+                GUIDES_BASE_PATH: '/custom/guides'
+            }
+        };
+        writeFileSync(join(testDir, '.mcp-config.json'), JSON.stringify(config));
+        const result = loadProjectConfig();
+        // Schema validation should fail on invalid field type
+        expect(result).toEqual({});
+        expect(loggedWarning).toBe(true);
+    });
+});
+//# sourceMappingURL=config-loading.test.js.map

package/dist/__tests__/config-loading.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loading.test.js","sourceRoot":"","sources":["../../src/__tests__/config-loading.test.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE1F,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,IAAI,OAAe,CAAC;IACpB,IAAI,WAAmB,CAAC;IACxB,IAAI,cAAkD,CAAC;IAEvD,UAAU,CAAC,GAAG,EAAE;QACd,8CAA8C;QAC9C,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,EAAE,mBAAmB,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC1D,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAExC,iDAAiD;QACjD,WAAW,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEvB,uDAAuD;QACvD,cAAc,GAAG,eAAe,EAAE,CAAC;QACnC,eAAe,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,uBAAuB;QACvB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAE3B,0BAA0B;QAC1B,IAAI,CAAC;YACH,MAAM,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,MAAM,CAAC;YACP,wBAAwB;QAC1B,CAAC;QAED,0BAA0B;QAC1B,eAAe,CAAC,cAAc,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACtE,MAAM,MAAM,GAAG;YACb,GAAG,EAAE;gBACH,kBAAkB,EAAE,cAAc;gBAClC,mBAAmB,EAAE,mBAAmB;gBACxC,gBAAgB,EAAE,gBAAgB;aACnC;SACF,CAAC;QAEF,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QAEzE,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,MAAM,UAAU,GAAG;YACjB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;YACrB,IAAI,EAAE,GAAS,EAAE,GAAG,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC;YAC3C,IAAI,EAAE,GAAS,EAAE,GAAE,CAAC;YACpB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;SACtB,CAAC;QACF,eAAe,CAAC,UAAU,CAAC,CAAC;QAE5B,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC,CAAC;QAErE,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+EAA+E,EAAE,GAAG,EAAE;QACvF,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,MAAM,UAAU,GAAG;YACjB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;YACrB,IAAI,EAAE,GAAS,EAAE,GAAG,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC;YAC3C,IAAI,EAAE,GAAS,EAAE,GAAE,CAAC;YACpB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;SACtB,CAAC;QACF,eAAe,CAAC,UAAU,CAAC,CAAC;QAE5B,MAAM,aAAa,GAAG;YACpB,MAAM,EAAE;gBACN,kBAAkB,EAAE,cAAc;aACnC;SACF,CAAC;QAEF,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;QAEhF,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,MAAM,UAAU,GAAG;YACjB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;YACrB,IAAI,EAAE,GAAS,EAAE,GAAG,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC;YAC3C,IAAI,EAAE,GAAS,EAAE,GAAE,CAAC;YACpB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;SACtB,CAAC;QACF,eAAe,CAAC,UAAU,CAAC,CAAC;QAE5B,MAAM,aAAa,GAAG;YACpB,GAAG,EAAE,eAAe;SACrB,CAAC;QAEF,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;QAEhF,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC/E,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,MAAM,UAAU,GAAG;YACjB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;YACrB,IAAI,EAAE,GAAS,EAAE,GAAG,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC;YAC3C,IAAI,EAAE,GAAS,EAAE,GAAE,CAAC;YACpB,KAAK,EAAE,GAAS,EAAE,GAAE,CAAC;SACtB,CAAC;QACF,eAAe,CAAC,UAAU,CAAC,CAAC;QAE5B,MAAM,MAAM,GAAG;YACb,GAAG,EAAE;gBACH,kBAAkB,EAAE,cAAc;gBAClC,mBAAmB,EAAE,GAAG,EAAE,4BAA4B;gBACtD,gBAAgB,EAAE,gBAAgB;aACnC;SACF,CAAC;QAEF,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QAEzE,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;QACnC,sDAAsD;QACtD,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/config-logging.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for configuration startup logging
+ */
+export {};
+//# sourceMappingURL=config-logging.test.d.ts.map

package/dist/__tests__/config-logging.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-logging.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config-logging.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/config-logging.test.js

@@ -0,0 +1,146 @@
+/**
+ * Tests for configuration startup logging
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { loadConfig } from '../config.js';
+import { getGlobalLogger, setGlobalLogger } from '../utils/logger.js';
+describe('config startup logging', () => {
+    let testDir;
+    let originalCwd;
+    let originalLogger;
+    let mockLogger;
+    let infoSpy;
+    beforeEach(() => {
+        // Create a temporary directory for test files
+        testDir = join(tmpdir(), `mcp-config-logging-test-${Date.now()}`);
+        mkdirSync(testDir, { recursive: true });
+        // Save original cwd and change to test directory
+        originalCwd = process.cwd();
+        process.chdir(testDir);
+        // Save original logger
+        originalLogger = getGlobalLogger();
+        // Create mock logger with spy
+        infoSpy = vi.fn();
+        mockLogger = {
+            error: vi.fn(),
+            warn: vi.fn(),
+            info: infoSpy,
+            debug: vi.fn()
+        };
+        setGlobalLogger(mockLogger);
+        // Set required MCP_WORKSPACE_PATH environment variable and create directory
+        const docsPath = join(testDir, 'docs');
+        mkdirSync(docsPath, { recursive: true });
+        process.env['MCP_WORKSPACE_PATH'] = docsPath;
+    });
+    afterEach(() => {
+        // Restore original cwd
+        process.chdir(originalCwd);
+        // Clean up test directory
+        try {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        // Restore original logger
+        setGlobalLogger(originalLogger);
+        // Clean up environment variables
+        delete process.env['MCP_WORKSPACE_PATH'];
+        delete process.env['WORKFLOWS_BASE_PATH'];
+        delete process.env['GUIDES_BASE_PATH'];
+        delete process.env['REFERENCE_EXTRACTION_DEPTH'];
+    });
+    it('logs configuration on startup with all required fields', () => {
+        loadConfig();
+        // Verify info() was called
+        expect(infoSpy).toHaveBeenCalled();
+        // Get the call arguments
+        const calls = infoSpy.mock.calls;
+        expect(calls.length).toBeGreaterThan(0);
+        // Check that message and context were provided
+        const [message, context] = calls[0];
+        expect(message).toBeTruthy();
+        expect(typeof message).toBe('string');
+        expect(context).toBeTruthy();
+        expect(typeof context).toBe('object');
+        // Verify all required fields are present in context
+        expect(context).toHaveProperty('projectRoot');
+        expect(context).toHaveProperty('workspacePath');
+        expect(context).toHaveProperty('workflowsPath');
+        expect(context).toHaveProperty('guidesPath');
+        expect(context).toHaveProperty('referenceExtractionDepth');
+        expect(context).toHaveProperty('hasProjectConfig');
+    });
+    it('logs resolved absolute paths', () => {
+        loadConfig();
+        const calls = infoSpy.mock.calls;
+        const [, context] = calls[0];
+        // Verify paths are absolute
+        expect(typeof context['workspacePath']).toBe('string');
+        expect(typeof context['workflowsPath']).toBe('string');
+        expect(typeof context['guidesPath']).toBe('string');
+        const workspacePath = context['workspacePath'];
+        const workflowsPath = context['workflowsPath'];
+        const guidesPath = context['guidesPath'];
+        expect(workspacePath).toMatch(/^[/\\]/); // Absolute path
+        expect(workflowsPath).toMatch(/^[/\\]/); // Absolute path
+        expect(guidesPath).toMatch(/^[/\\]/); // Absolute path
+    });
+    it('logs hasProjectConfig as false when no .mcp-config.json exists', () => {
+        loadConfig();
+        const calls = infoSpy.mock.calls;
+        const [, context] = calls[0];
+        expect(context['hasProjectConfig']).toBe(false);
+    });
+    it('logs hasProjectConfig as true when .mcp-config.json exists', () => {
+        const customDocsPath = join(testDir, 'custom-docs');
+        mkdirSync(customDocsPath, { recursive: true });
+        const config = {
+            env: {
+                MCP_WORKSPACE_PATH: customDocsPath
+            }
+        };
+        writeFileSync(join(testDir, '.mcp-config.json'), JSON.stringify(config));
+        loadConfig();
+        const calls = infoSpy.mock.calls;
+        const [, context] = calls[0];
+        expect(context['hasProjectConfig']).toBe(true);
+    });
+    it('logs custom reference extraction depth from environment', () => {
+        process.env['REFERENCE_EXTRACTION_DEPTH'] = '5';
+        loadConfig();
+        const calls = infoSpy.mock.calls;
+        const [, context] = calls[0];
+        expect(context['referenceExtractionDepth']).toBe(5);
+    });
+    it('logs default reference extraction depth when not specified', () => {
+        loadConfig();
+        const calls = infoSpy.mock.calls;
+        const [, context] = calls[0];
+        expect(context['referenceExtractionDepth']).toBe(3); // Default from DEFAULT_CONFIG
+    });
+    it('uses getGlobalLogger() not console.log', () => {
+        const consoleSpy = vi.spyOn(console, 'log');
+        const consoleErrorSpy = vi.spyOn(console, 'error');
+        const consoleWarnSpy = vi.spyOn(console, 'warn');
+        loadConfig();
+        // Verify console methods were not called directly
+        expect(consoleSpy).not.toHaveBeenCalled();
+        // console.error/warn might be called by logger, but not console.log
+        consoleSpy.mockRestore();
+        consoleErrorSpy.mockRestore();
+        consoleWarnSpy.mockRestore();
+    });
+    it('logs message describing configuration startup', () => {
+        loadConfig();
+        const calls = infoSpy.mock.calls;
+        const [message] = calls[0];
+        // Message should describe configuration or startup
+        expect(message.toLowerCase()).toMatch(/(configuration|config|startup|loaded)/);
+    });
+});
+//# sourceMappingURL=config-logging.test.js.map

package/dist/__tests__/config-logging.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-logging.test.js","sourceRoot":"","sources":["../../src/__tests__/config-logging.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/config-path-resolution.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for path resolution utilities
+ */
+export {};
+//# sourceMappingURL=config-path-resolution.test.d.ts.map

package/dist/__tests__/config-path-resolution.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-path-resolution.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config-path-resolution.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}