dev-mcp-server 0.0.2

package/.env.example

@@ -0,0 +1,68 @@
+# ═══════════════════════════════════════════════════════════════
+#  Dev MCP Server — environment configuration
+#  Copy this file to .env and fill in your values.
+# ═══════════════════════════════════════════════════════════════
+
+# ── LLM Provider ───────────────────────────────────────────────
+# Which LLM backend to use.
+# Options: anthropic | ollama | azure
+# Default: anthropic
+LLM_PROVIDER=anthropic
+
+# Model / deployment name override.
+# If unset, the default per provider is used:
+#   anthropic → claude-opus-4-5
+#   ollama    → llama3
+#   azure     → MUST be set (matches your Azure deployment name)
+# LLM_MODEL=claude-opus-4-5
+
+
+# ── Anthropic ──────────────────────────────────────────────────
+# Required when LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+
+# ── Ollama ─────────────────────────────────────────────────────
+# Required when LLM_PROVIDER=ollama
+# Ensure Ollama is running: https://ollama.com
+# Pull a model first:  ollama pull llama3
+#
+# OLLAMA_BASE_URL=http://localhost:11434
+
+
+# ── Azure OpenAI ───────────────────────────────────────────────
+# Required when LLM_PROVIDER=azure
+#
+# Your Azure OpenAI resource endpoint:
+# AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com
+#
+# API key from Azure portal → Keys and Endpoint:
+# AZURE_OPENAI_API_KEY=your-azure-key-here
+#
+# The name of the deployment you created in Azure AI Studio
+# (this is also used as the model parameter):
+# AZURE_OPENAI_DEPLOYMENT=gpt-4o
+#
+# API version — default is fine unless you need a specific one:
+# AZURE_OPENAI_API_VERSION=2024-05-01-preview
+
+
+# ── Ingestion — ignore rules ────────────────────────────────────
+# Whether to read the project's .gitignore and add its patterns
+# to the ingest ignore list. Set to "false" to disable.
+# Default: true
+# INGEST_USE_GITIGNORE=true
+
+# Extra glob patterns to ignore during ingest (comma-separated).
+# Added on top of the built-in baseline and .gitignore patterns.
+# Example: INGEST_EXTRA_IGNORE=**/fixtures/**,**/__snapshots__/**
+# INGEST_EXTRA_IGNORE=
+
+
+# ── Server ─────────────────────────────────────────────────────
+PORT=3000
+
+
+# ── Logging ────────────────────────────────────────────────────
+# Options: error | warn | info | debug
+LOG_LEVEL=info

package/README.md

@@ -0,0 +1,333 @@
+# 🧠 Dev MCP Server — Model Context Platform
+
+> AI that understands **your** codebase, not just the internet.
+
+Inspired by *"How I Built an MCP Server That Made Developers Faster and Work Easier"* — a full implementation of the **Model Context Platform** concept: instead of generic AI answers, every response is grounded in your actual code, error logs, API behavior, and bug history.
+
+---
+
+## The Problem It Solves
+
+Every team has this invisible tax:
+- Debugging code you didn't write, with zero context
+- Explaining things that are already written *somewhere*
+- Digging through 10 files to understand one API
+- Answering the same question for the third time this week
+
+The root cause isn't bad code. It's a **context problem** — knowledge scattered across services, logs, configs, and people's heads.
+
+---
+
+## What It Does
+
+Before answering any question, the AI looks up your **actual system**. It knows:
+
+- Your data models and DTOs
+- Your naming conventions and code patterns
+- Your most common bugs and how you fixed them
+- Your API behaviour — including weird edge cases
+- How your modules connect to each other
+
+---
+
+## The 3 Core Queries
+
+| Query                                | Endpoint                 | Example                                              |
+| ------------------------------------ | ------------------------ | ---------------------------------------------------- |
+| 🐛 **Why is this failing?**           | `POST /api/query/debug`  | `"Why is ClassCastException thrown in UserService?"` |
+| 🔍 **Where is this used?**            | `POST /api/query/usage`  | `"Where is getUserById called?"`                     |
+| 💥 **If I change this, what breaks?** | `POST /api/query/impact` | `"If I change the User model, what breaks?"`         |
+
+---
+
+## Quick Start
+
+### Option A — via npx (no install required)
+
+```bash
+# In your project root (where your .env lives):
+npx dev-mcp-server ingest ./src
+npx dev-mcp-server query "Why is getUserById throwing?"
+npx dev-mcp-server query -i   # interactive REPL
+```
+
+> **Note:** `npx` will look for `.env` in the directory you run the command from,
+> so make sure your credentials are there before running.
+
+### Option B — local install
+
+```bash
+git clone <repo>
+cd dev-mcp-server
+npm install
+cp .env.example .env
+# Edit .env — choose your LLM provider and add credentials
+```
+
+```bash
+# Ingest your codebase
+node cli.js ingest ./src
+
+# Ask questions
+node cli.js query -i                          # interactive REPL
+node cli.js query "Why is getUserById failing?"
+node cli.js debug "ClassCastException" --stack "at UserService:45"
+node cli.js stats
+```
+
+### Option C — REST API server
+
+```bash
+npm start
+# Runs at http://localhost:3000
+```
+
+---
+
+## LLM Providers
+
+The server supports three backends. Switch between them with a single environment variable — no code changes needed.
+
+### Anthropic (default)
+
+```env
+LLM_PROVIDER=anthropic
+ANTHROPIC_API_KEY=sk-ant-your-key-here
+LLM_MODEL=claude-opus-4-5          # optional, this is the default
+```
+
+### Ollama (local / self-hosted)
+
+Run any model locally — no API key needed.
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull llama3      # or mistral, codellama, phi3, etc.
+```
+
+```env
+LLM_PROVIDER=ollama
+OLLAMA_BASE_URL=http://localhost:11434   # optional, this is the default
+LLM_MODEL=llama3                        # optional, this is the default
+```
+
+### Azure OpenAI
+
+```env
+LLM_PROVIDER=azure
+AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com
+AZURE_OPENAI_API_KEY=your-azure-key-here
+AZURE_OPENAI_DEPLOYMENT=gpt-4o          # your deployment name in Azure AI Studio
+AZURE_OPENAI_API_VERSION=2024-05-01-preview   # optional, has a sensible default
+```
+
+> The deployment name is also used as `LLM_MODEL`. If you want to override the model
+> label independently, set `LLM_MODEL` explicitly.
+
+---
+
+## Ingest & Ignore Rules
+
+### Default ignore list
+
+The following patterns are always excluded, regardless of any other configuration:
+
+```
+**/node_modules/**    **/.git/**        **/dist/**
+**/build/**           **/coverage/**    **/*.min.js
+**/package-lock.json  **/yarn.lock
+```
+
+### .gitignore integration
+
+By default the server reads the `.gitignore` in the directory being ingested and adds those patterns on top of the baseline. This means anything your team already ignores in git is also ignored during ingestion — no duplicate config.
+
+```env
+# Disable .gitignore integration (enabled by default):
+INGEST_USE_GITIGNORE=false
+```
+
+### Extra ignore patterns
+
+Add any additional glob patterns via a comma-separated env var:
+
+```env
+INGEST_EXTRA_IGNORE=**/fixtures/**,**/__snapshots__/**,**/test-data/**
+```
+
+All three sources (baseline + `.gitignore` + `INGEST_EXTRA_IGNORE`) are merged and deduplicated before each directory ingest. The log output tells you exactly what was applied:
+
+```
+Ignore sources: baseline, .gitignore (12 patterns), INGEST_EXTRA_IGNORE (2 patterns)
+```
+
+---
+
+## Configuration Reference
+
+Copy `.env.example` to `.env` and fill in the relevant section for your chosen provider.
+
+| Variable                   | Default                  | Description                                     |
+| -------------------------- | ------------------------ | ----------------------------------------------- |
+| `LLM_PROVIDER`             | `anthropic`              | LLM backend: `anthropic` \| `ollama` \| `azure` |
+| `LLM_MODEL`                | *(per provider)*         | Model or deployment name override               |
+| `ANTHROPIC_API_KEY`        | —                        | Required when `LLM_PROVIDER=anthropic`          |
+| `OLLAMA_BASE_URL`          | `http://localhost:11434` | Ollama server URL                               |
+| `AZURE_OPENAI_ENDPOINT`    | —                        | Required when `LLM_PROVIDER=azure`              |
+| `AZURE_OPENAI_API_KEY`     | —                        | Required when `LLM_PROVIDER=azure`              |
+| `AZURE_OPENAI_DEPLOYMENT`  | —                        | Required when `LLM_PROVIDER=azure`              |
+| `AZURE_OPENAI_API_VERSION` | `2024-05-01-preview`     | Azure API version                               |
+| `INGEST_USE_GITIGNORE`     | `true`                   | Read `.gitignore` during ingest                 |
+| `INGEST_EXTRA_IGNORE`      | —                        | Comma-separated extra glob patterns to ignore   |
+| `PORT`                     | `3000`                   | HTTP server port                                |
+| `LOG_LEVEL`                | `info`                   | `error` \| `warn` \| `info` \| `debug`          |
+
+---
+
+## API Reference
+
+### Ingest
+
+```bash
+# Ingest a file
+curl -X POST http://localhost:3000/api/ingest/file \
+  -H "Content-Type: application/json" \
+  -d '{"filePath": "./src/services/UserService.js"}'
+
+# Ingest a directory
+curl -X POST http://localhost:3000/api/ingest/directory \
+  -H "Content-Type: application/json" \
+  -d '{"dirPath": "./src"}'
+
+# Ingest raw text (paste an error log, bug description, etc.)
+curl -X POST http://localhost:3000/api/ingest/raw \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "ClassCastException at UserService line 45: Mongoose doc passed to UserDTO. Fix: call .toObject() first.",
+    "kind": "log",
+    "label": "production-bug-2024-03-15"
+  }'
+```
+
+### Query
+
+```bash
+# General question — auto-detects debug / usage / impact mode
+curl -X POST http://localhost:3000/api/query \
+  -H "Content-Type: application/json" \
+  -d '{"question": "Why does getUserById sometimes throw ClassCastException?"}'
+
+# Force debug mode
+curl -X POST http://localhost:3000/api/query/debug \
+  -H "Content-Type: application/json" \
+  -d '{"error": "ClassCastException", "stackTrace": "at UserService.getUserById:45"}'
+
+# Usage search
+curl -X POST http://localhost:3000/api/query/usage \
+  -H "Content-Type: application/json" \
+  -d '{"symbol": "getUserById"}'
+
+# Impact analysis
+curl -X POST http://localhost:3000/api/query/impact \
+  -H "Content-Type: application/json" \
+  -d '{"target": "UserDTO", "changeDescription": "add a new required field"}'
+
+# Streaming (Server-Sent Events)
+curl -X POST http://localhost:3000/api/query/stream \
+  -H "Content-Type: application/json" \
+  -d '{"question": "How does user status update work end to end?"}'
+```
+
+### Knowledge Base
+
+```bash
+curl http://localhost:3000/api/knowledge/stats
+curl "http://localhost:3000/api/knowledge/search?q=ClassCastException&topK=5"
+curl http://localhost:3000/api/knowledge/files
+curl -X POST http://localhost:3000/api/knowledge/rebuild
+curl -X DELETE http://localhost:3000/api/ingest/clear
+```
+
+---
+
+## Supported File Types
+
+| Category | Extensions                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------ |
+| Code     | `.js` `.ts` `.jsx` `.tsx` `.mjs` `.cjs` `.py` `.java` `.go` `.rb` `.php` `.cs` `.cpp` `.c` `.rs` |
+| Config   | `.json` `.yaml` `.yml` `.env` `.toml` `.xml`                                                     |
+| Docs     | `.md` `.txt`                                                                                     |
+| Logs     | `.log`                                                                                           |
+| Schema   | `.sql` `.graphql` `.gql`                                                                         |
+| Scripts  | `.sh` `.bash`                                                                                    |
+
+---
+
+## What to Ingest
+
+The key insight: **ingest real stuff, not clean summaries**.
+
+```bash
+node cli.js ingest ./src          # actual source code
+node cli.js ingest ./logs         # real error logs — the ugly ones
+node cli.js ingest ./config       # environment configs and schemas
+node cli.js ingest ./docs         # ADRs, runbooks, onboarding notes
+```
+
+Paste knowledge directly in the interactive REPL:
+
+```
+❯ node cli.js query -i
+❯ We fixed a bug last week where the Mongoose document wasn't being converted
+  to a plain object before passing to UserDTO. Always call .toObject() first.
+```
+
+> *"Docs lie. Or rather, docs go stale. Code doesn't."*
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Dev MCP Server                                  │
+│                                                                      │
+│  ┌──────────┐    ┌──────────┐    ┌────────────────────────┐  │
+│  │ Ingester  │───▶│  Store    │──▶│        Indexer             │  │
+│  │           │     │ (JSON)    │    │   (TF-IDF Search)          │  │
+│  └──────────┘    └──────────┘    └────────────────────────┘  │
+│       │                                      │               │
+│       ▼                                      ▼               │
+│  ┌──────────┐                  ┌───────────────────────────┐ │
+│  │   CLI     │                  │       Query Engine        │ │
+│  │  (REPL)   │                  │  Retrieval + LLM Client   │ │
+│  └──────────┘                  └───────────────────────────┘ │
+│                                              │                │
+│                                             ┌┴──────────────┐│
+│                                             │  Anthropic /  ││
+│                                             │  Ollama /     ││
+│                                             │  Azure OpenAI ││
+│                                             └───────────────┘│
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐  │
+│  │                    Express REST API                     │  │
+│  └────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**How it works:**
+1. **Ingest** — Feed your codebase in (files, directories, raw text)
+2. **Index** — TF-IDF search index built over all chunks
+3. **Query** — Question arrives → relevant context retrieved → LLM answers based on *your* code
+
+---
+
+## Key Design Decisions
+
+**Data quality beats model quality.** The retrieval step (TF-IDF over your actual files) matters more than which AI model you use. A focused, well-curated knowledge base with a smaller model will outperform a bloated one with GPT-4.
+
+**No embeddings, no vector DB.** TF-IDF is deterministic, fast, and requires zero infrastructure. For most codebases (< 50k files) it's entirely sufficient.
+
+**Provider-agnostic by design.** The `llmClient` abstraction means you can switch from Anthropic to a local Ollama model to Azure OpenAI by changing one line in `.env` — useful for cost control, data residency requirements, or offline usage.
+
+**Ingest real artefacts.** Error logs, not summaries of error logs. Actual API responses, not docs about API responses. The messier the better — the system is built to handle it.

package/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+const path = require('path');
+require('dotenv').config({ path: path.resolve(process.cwd(), '.env') });
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const readline = require('readline');
+
+const ingester = require('./src/core/ingester');
+const indexer = require('./src/core/indexer');
+const { QueryEngine, detectMode, QUERY_MODES } = require('./src/core/queryEngine');
+const store = require('./src/storage/store');
+
+const program = new Command();
+
+const banner = chalk.cyan(`
+╔══════════════════════════════════════════════════════╗
+║     Dev MCP Server — Model Context Platform          ║
+║     AI that understands YOUR codebase                ║
+╚══════════════════════════════════════════════════════╝
+`);
+
+program
+    .command('ingest <path>')
+    .description('Ingest a file or directory into the knowledge base')
+    .option('-t, --type <type>', 'Force type: code | config | documentation | log | schema')
+    .action(async (inputPath, opts) => {
+        console.log(banner);
+        const fs = require('fs');
+        const stat = fs.statSync(inputPath);
+        const spinner = ora();
+
+        if (stat.isDirectory()) {
+            spinner.start(chalk.blue(`Scanning directory: ${inputPath}`));
+            try {
+                const result = await ingester.ingestDirectory(inputPath);
+                spinner.succeed(chalk.green('Ingestion complete'));
+                console.log('\n' + chalk.bold('Results:'));
+                console.log(`  ${chalk.green('✓')} Ingested: ${result.ingested} files`);
+                console.log(`  ${chalk.yellow('⚠')} Skipped:  ${result.skipped} files`);
+                console.log(`  ${chalk.red('✗')} Failed:   ${result.failed} files`);
+                console.log(`  ${chalk.cyan('◈')} Chunks:   ${result.totalChunks} total`);
+                if (result.errors.length > 0) {
+                    console.log('\n' + chalk.red('Errors:'));
+                    result.errors.slice(0, 5).forEach(e =>
+                        console.log(`  ${e.file}: ${e.error}`)
+                    );
+                }
+            } catch (err) {
+                spinner.fail(chalk.red(`Failed: ${err.message}`));
+                process.exit(1);
+            }
+        } else {
+            spinner.start(chalk.blue(`Ingesting file: ${inputPath}`));
+            try {
+                const result = await ingester.ingestFile(inputPath);
+                indexer.build();
+                spinner.succeed(chalk.green(`Ingested: ${result.chunks} chunks`));
+            } catch (err) {
+                spinner.fail(chalk.red(`Failed: ${err.message}`));
+                process.exit(1);
+            }
+        }
+    });
+
+program
+    .command('query [question]')
+    .description('Ask a question about your codebase')
+    .option('-m, --mode <mode>', 'Force mode: debug | usage | impact | general')
+    .option('-k, --top-k <n>', 'Number of context chunks', '8')
+    .option('-i, --interactive', 'Start interactive REPL session')
+    .action(async (question, opts) => {
+        console.log(banner);
+
+        const stats = store.getStats();
+        if (stats.totalDocs === 0) {
+            console.log(chalk.yellow('⚠  Knowledge base is empty!'));
+            console.log(chalk.gray('   Run: node cli.js ingest <path>'));
+            process.exit(1);
+        }
+
+        console.log(chalk.gray(`📚 Knowledge base: ${stats.totalDocs} docs from ${stats.totalFiles} files\n`));
+
+        if (opts.interactive || !question) {
+            await startRepl();
+            return;
+        }
+
+        await askQuestion(question, opts);
+    });
+
+async function askQuestion(question, opts = {}) {
+    const mode = opts.mode || detectMode(question);
+    const topK = parseInt(opts.topK || 8);
+
+    const modeColors = {
+        [QUERY_MODES.DEBUG]: chalk.red,
+        [QUERY_MODES.USAGE]: chalk.blue,
+        [QUERY_MODES.IMPACT]: chalk.yellow,
+        [QUERY_MODES.GENERAL]: chalk.cyan,
+    };
+
+    const modeEmoji = {
+        [QUERY_MODES.DEBUG]: '🐛',
+        [QUERY_MODES.USAGE]: '🔍',
+        [QUERY_MODES.IMPACT]: '💥',
+        [QUERY_MODES.GENERAL]: '💬',
+    };
+
+    const colorFn = modeColors[mode] || chalk.cyan;
+    console.log(colorFn(`${modeEmoji[mode]} Mode: ${mode.toUpperCase()}`));
+    console.log(chalk.bold(`\nQ: ${question}\n`));
+
+    const spinner = ora('Retrieving context and thinking...').start();
+
+    try {
+        const result = await QueryEngine.query(question, { mode, topK });
+        spinner.stop();
+
+        console.log(chalk.gray('─'.repeat(60)));
+        console.log(chalk.gray('Sources used:'));
+        result.sources.forEach((s, i) => {
+            console.log(chalk.gray(`  [${i + 1}] ${s.file} (${s.kind}) — score: ${s.relevanceScore}`));
+        });
+        console.log(chalk.gray('─'.repeat(60)));
+
+        console.log('\n' + chalk.bold('Answer:\n'));
+        console.log(result.answer);
+        console.log(chalk.gray(`\n[Tokens: ${result.usage.inputTokens} in / ${result.usage.outputTokens} out]`));
+
+    } catch (err) {
+        spinner.fail(chalk.red(`Error: ${err.message}`));
+    }
+}
+
+async function startRepl() {
+    console.log(chalk.cyan('Starting interactive session. Type "exit" to quit, "help" for tips.\n'));
+
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    const prompt = () => {
+        rl.question(chalk.bold.cyan('\n❯ '), async (input) => {
+            const trimmed = input.trim();
+
+            if (!trimmed) {
+                prompt();
+                return;
+            }
+
+            if (trimmed.toLowerCase() === 'exit' || trimmed.toLowerCase() === 'quit') {
+                console.log(chalk.cyan('\nGoodbye!\n'));
+                rl.close();
+                process.exit(0);
+            }
+
+            if (trimmed.toLowerCase() === 'help') {
+                console.log(chalk.cyan(`
+Tips:
+  🐛 Debug:  "Why is ClassCastException happening in UserService?"
+  🔍 Usage:  "Where is getUserById used?"
+  💥 Impact: "If I change the User model, what breaks?"
+  💬 General: Any question about your codebase
+        `));
+                prompt();
+                return;
+            }
+
+            if (trimmed.toLowerCase() === 'stats') {
+                const stats = store.getStats();
+                console.log(chalk.cyan(JSON.stringify(stats, null, 2)));
+                prompt();
+                return;
+            }
+
+            await askQuestion(trimmed);
+            prompt();
+        });
+    };
+
+    prompt();
+}
+
+program
+    .command('stats')
+    .description('Show knowledge base statistics')
+    .action(() => {
+        const stats = store.getStats();
+        const files = store.getIngestedFiles();
+
+        console.log(banner);
+        console.log(chalk.bold('Knowledge Base Stats:'));
+        console.log(`  Total documents: ${chalk.green(stats.totalDocs)}`);
+        console.log(`  Total files:     ${chalk.green(stats.totalFiles)}`);
+        console.log(`  Last ingested:   ${chalk.gray(stats.lastIngested || 'Never')}`);
+        console.log('\n' + chalk.bold('By type:'));
+        Object.entries(stats.fileTypes || {}).forEach(([type, count]) => {
+            console.log(`  ${type.padEnd(15)} ${chalk.cyan(count)} docs`);
+        });
+
+        if (files.length > 0) {
+            console.log('\n' + chalk.bold(`Ingested files (${files.length}):`));
+            files.slice(0, 20).forEach(f => console.log(`  ${chalk.gray(f)}`));
+            if (files.length > 20) {
+                console.log(chalk.gray(`  ... and ${files.length - 20} more`));
+            }
+        }
+    });
+
+program
+    .command('clear')
+    .description('Clear the entire knowledge base')
+    .option('-y, --yes', 'Skip confirmation')
+    .action(async (opts) => {
+        if (!opts.yes) {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            rl.question(chalk.red('⚠  This will delete all indexed data. Continue? (y/N) '), (answer) => {
+                rl.close();
+                if (answer.toLowerCase() === 'y') {
+                    store.clear();
+                    indexer.invalidate();
+                    console.log(chalk.green('✓ Knowledge base cleared'));
+                } else {
+                    console.log('Cancelled.');
+                }
+                process.exit(0);
+            });
+        } else {
+            store.clear();
+            indexer.invalidate();
+            console.log(chalk.green('✓ Knowledge base cleared'));
+        }
+    });
+
+program
+    .command('debug <error>')
+    .description('Quick debug: explain an error in context of your codebase')
+    .option('-s, --stack <trace>', 'Stack trace')
+    .action(async (error, opts) => {
+        console.log(banner);
+        await askQuestion(`Why is this error happening and how do I fix it?\nError: ${error}${opts.stack ? '\nStack:\n' + opts.stack : ''}`, { mode: QUERY_MODES.DEBUG });
+    });
+
+program.parse(process.argv);