merlyn-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christian Cattaneo
+
+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,108 @@
+# merlyn
+
+local development coach with MCP server, interactive TUI, and AI-powered analysis. a stripped-down fork of [midas-mcp](https://github.com/christiancattaneo/midas-mcp) with all cloud/dashboard/pilot code removed.
+
+## what it does
+
+merlyn tracks your project phase and tells you what to do next.
+
+1. run `merlyn` -- TUI starts, analyzes your project with AI
+2. AI detects your phase -- PLAN / BUILD / SHIP / GROW
+3. shows a suggested prompt -- "do this next" with explanation
+4. press **[c]** to copy the prompt, paste in Cursor
+5. Cursor calls MCP tools -- `midas_analyze`, `midas_verify`, etc.
+6. tools update state -- phase advances, progress tracked
+7. next time you run `merlyn` -- knows where you left off
+
+## quick start
+
+```bash
+npx merlyn-mcp
+```
+
+launches the interactive TUI coach. press `?` for help.
+
+### cursor MCP config
+
+add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "merlyn": {
+      "command": "npx",
+      "args": ["merlyn-mcp", "server"]
+    }
+  }
+}
+```
+
+37 tools, 20 prompts, 5 resources -- all local, no cloud.
+
+## CLI commands
+
+```
+merlyn-mcp                interactive coach (recommended)
+merlyn-mcp status         show current phase and progress
+merlyn-mcp init <name>    initialize new project
+merlyn-mcp audit          audit against 12 ingredients
+merlyn-mcp docs           check planning docs
+merlyn-mcp metrics        session metrics
+merlyn-mcp weekly         weekly suggestion patterns
+merlyn-mcp server         start MCP server
+merlyn-mcp help           show help
+```
+
+## the four phases
+
+**PLAN** -- idea, research, PRD, gameplan. understand what you're building before you build it.
+
+**BUILD** -- rules, index, read, research, implement, test, debug. the 7-step cycle. if stuck 3+ times, tornado: research + logs + tests.
+
+**SHIP** -- review, deploy, monitor. gates must pass (build, test, lint) before advancing.
+
+**GROW** -- feedback, analyze, iterate. collect data, triage, plan next cycle.
+
+## key tools
+
+the MCP tools keep `midas_` prefix for compatibility with existing cursor configs.
+
+- `midas_analyze` -- AI analysis of project state and phase
+- `midas_suggest_prompt` -- get phase-appropriate next action
+- `midas_advance_phase` -- move to next step/phase
+- `midas_verify` -- run build/test/lint gates
+- `midas_journal_save` -- save conversation context
+- `midas_tornado` -- research + logs + tests debugging cycle
+- `midas_oneshot` -- construct retry prompt from error
+- `midas_horizon` -- expand context when output doesn't fit
+- `midas_start_hotfix` -- emergency bug fix mode
+- `midas_completeness` -- 12-category production readiness score
+- `midas_vuln_scan` -- security vulnerability scanner
+
+## three principles
+
+**oneshot** -- when things break, go back with original prompt + error + "avoid this" instead of patching forward.
+
+**tornado** -- three forces spinning together solve any problem: research + logs + tests.
+
+**horizon** -- AI thinks vertical (implementation). you provide horizontal (context). wrong output means widen your context.
+
+## AI analysis
+
+merlyn uses the Anthropic API for smart project analysis. optional but recommended (~$0.003/analysis). configure in `~/.midas/config.json` or press `k` in the TUI.
+
+without an API key, merlyn falls back to deterministic local analysis based on file presence and git history.
+
+## development
+
+```bash
+git clone https://github.com/christiancattaneo/merlyn-mcp
+cd merlyn
+npm install
+npm run build
+npm test
+```
+
+## license
+
+MIT

package/dist/ai.d.ts

@@ -0,0 +1,16 @@
+import { getCurrentModel } from './providers.js';
+export interface CodebaseContext {
+    files: string[];
+    summary: string;
+    techStack: string[];
+    suggestedNextStep: string;
+}
+export declare function analyzeCodebase(projectPath: string): Promise<CodebaseContext>;
+export declare function generateSmartPrompt(projectPath: string, phase: string, step: string, context?: CodebaseContext): Promise<string>;
+export declare function detectStepCompletion(projectPath: string, currentStep: string): Promise<{
+    completed: boolean;
+    confidence: number;
+    reason: string;
+}>;
+export { getCurrentModel };
+//# sourceMappingURL=ai.d.ts.map

package/dist/ai.js

@@ -0,0 +1,141 @@
+import { getApiKey } from './config.js';
+import { chat, getCurrentModel, getProviderCapabilities } from './providers.js';
+import { getActiveProvider } from './config.js';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { discoverAndReadCode } from './code-discovery.js';
+export async function analyzeCodebase(projectPath) {
+    const apiKey = getApiKey();
+    // Use intelligent code discovery
+    const codeResult = discoverAndReadCode(projectPath);
+    const files = codeResult.files.map(f => f.path);
+    if (!apiKey) {
+        // Return basic analysis without AI
+        const techStack = [];
+        // Detect tech stack from files
+        const hasPackageJson = existsSync(join(projectPath, 'package.json'));
+        const hasTsConfig = existsSync(join(projectPath, 'tsconfig.json'));
+        const hasRequirements = existsSync(join(projectPath, 'requirements.txt'));
+        const hasCargoToml = existsSync(join(projectPath, 'Cargo.toml'));
+        if (hasPackageJson)
+            techStack.push('Node.js');
+        if (hasTsConfig)
+            techStack.push('TypeScript');
+        if (hasRequirements)
+            techStack.push('Python');
+        if (hasCargoToml)
+            techStack.push('Rust');
+        if (files.some(f => f.includes('react') || f.endsWith('.tsx') || f.endsWith('.jsx')))
+            techStack.push('React');
+        return {
+            files,
+            summary: `Found ${codeResult.totalFiles} source files`,
+            techStack,
+            suggestedNextStep: 'Continue with current phase',
+        };
+    }
+    try {
+        const provider = getActiveProvider();
+        const capabilities = getProviderCapabilities(provider);
+        const response = await chat(`Analyze this codebase and provide:
+1. A one-line summary of what it does
+2. The tech stack (list)
+3. The most important next step for production readiness
+
+${codeResult.fileList}
+
+${codeResult.codeContext}
+
+Respond in JSON format:
+{"summary": "...", "techStack": ["..."], "suggestedNextStep": "..."}`, {
+            systemPrompt: 'You are a senior engineer analyzing a codebase. Be concise. Respond only with valid JSON.',
+            useThinking: capabilities.thinking,
+        });
+        const parsed = JSON.parse(response.content);
+        return {
+            files,
+            summary: parsed.summary || `Found ${codeResult.totalFiles} source files`,
+            techStack: parsed.techStack || [],
+            suggestedNextStep: parsed.suggestedNextStep || 'Continue with current phase',
+        };
+    }
+    catch {
+        return {
+            files,
+            summary: `Found ${codeResult.totalFiles} source files`,
+            techStack: [],
+            suggestedNextStep: 'Continue with current phase',
+        };
+    }
+}
+export async function generateSmartPrompt(projectPath, phase, step, context) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        return ''; // Fall back to default prompts
+    }
+    const codebaseContext = context || await analyzeCodebase(projectPath);
+    const provider = getActiveProvider();
+    const capabilities = getProviderCapabilities(provider);
+    try {
+        const response = await chat(`Generate a specific, actionable prompt for a developer to paste into Cursor AI.
+
+Project: ${codebaseContext.summary}
+Tech stack: ${codebaseContext.techStack.join(', ')}
+Current phase: ${phase}
+Current step: ${step}
+
+The prompt should:
+1. Be specific to THIS codebase
+2. Reference actual files/patterns if known
+3. Be immediately actionable
+4. Follow the Prompt Wizard methodology
+
+Respond with just the prompt text, no explanation.`, {
+            systemPrompt: 'You are Merlyn, a code wizard and development coach. Generate prompts that are specific, actionable, and context-aware.',
+            useThinking: capabilities.thinking,
+        });
+        return response.content.trim();
+    }
+    catch {
+        return '';
+    }
+}
+export async function detectStepCompletion(projectPath, currentStep) {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        return { completed: false, confidence: 0, reason: 'No API key' };
+    }
+    const context = await analyzeCodebase(projectPath);
+    const provider = getActiveProvider();
+    const capabilities = getProviderCapabilities(provider);
+    try {
+        const response = await chat(`Based on this codebase analysis, determine if the following step is complete:
+
+Step: ${currentStep}
+Files: ${context.files.length} source files
+Tech stack: ${context.techStack.join(', ')}
+
+Consider:
+- IDEA: Is there a clear project purpose?
+- RESEARCH: Are there docs about alternatives?
+- PRD: Is there a prd.md with requirements?
+- GAMEPLAN: Is there a gameplan.md with plan?
+- BUILD steps: Is there working code with tests?
+
+Respond in JSON:
+{"completed": true/false, "confidence": 0-100, "reason": "..."}`, {
+            systemPrompt: 'You are analyzing project completeness. Be conservative - only mark complete if clearly done.',
+            useThinking: capabilities.thinking,
+        });
+        return JSON.parse(response.content);
+    }
+    catch (error) {
+        const reason = error instanceof Error
+            ? `Analysis failed: ${error.message.slice(0, 40)}`
+            : 'Analysis failed: unknown error';
+        return { completed: false, confidence: 0, reason };
+    }
+}
+// Re-export for backward compatibility
+export { getCurrentModel };
+//# sourceMappingURL=ai.js.map

package/dist/analyzer.d.ts

@@ -0,0 +1,64 @@
+import type { Phase } from './state/phase.js';
+/**
+ * Summarize long content using Claude (with caching for efficiency)
+ * Use for: journal entries, long error logs, large code files
+ */
+export declare function summarizeContent(content: string, purpose: string, targetTokens?: number): Promise<string>;
+export interface ProjectAnalysis {
+    currentPhase: Phase;
+    summary: string;
+    whatsDone: string[];
+    whatsNext: string;
+    suggestedPrompt: string;
+    confidence: number;
+    techStack: string[];
+}
+export interface DeterministicProgress {
+    percentage: number;
+    breakdown: {
+        planning: number;
+        implementation: number;
+        quality: number;
+    };
+    label: string;
+}
+/**
+ * Calculate progress deterministically from artifacts, not AI assessment.
+ *
+ * Formula:
+ * - PLAN phase: planning docs progress (prd, gameplan)
+ * - BUILD phase: gameplan task completion
+ * - SHIP phase: gates + preflight checks
+ * - GROW phase: deployment + monitoring artifacts
+ */
+export declare function calculateDeterministicProgress(projectPath: string): DeterministicProgress;
+export declare function analyzeProject(projectPath: string): Promise<ProjectAnalysis>;
+export interface AnalysisProgress {
+    stage: 'gathering' | 'connecting' | 'thinking' | 'streaming' | 'parsing' | 'complete';
+    message: string;
+    elapsedMs: number;
+    tokensReceived?: number;
+    partialContent?: string;
+}
+export type AnalysisProgressCallback = (progress: AnalysisProgress) => void;
+/**
+ * Analyze project with real-time streaming progress
+ * Use this for TUI to show accurate progress feedback
+ */
+export declare function analyzeProjectStreaming(projectPath: string, onProgress?: AnalysisProgressCallback): Promise<ProjectAnalysis>;
+export interface ResponseAnalysis {
+    summary: string;
+    accomplished: string[];
+    errors: string[];
+    filesChanged: string[];
+    taskComplete: boolean;
+    suggestedNextPrompt: string;
+    shouldAdvancePhase: boolean;
+    confidence: number;
+}
+/**
+ * Analyze a pasted AI response to extract insights
+ * This bridges the gap between Cursor chat and Merlyn tracking
+ */
+export declare function analyzeResponse(projectPath: string, userPrompt: string, aiResponse: string): Promise<ResponseAnalysis>;
+//# sourceMappingURL=analyzer.d.ts.map