@simpletoolsindiaorg/engi-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-03-16
+
+### Added
+- 12 MCP tools across 5 capability modules (analysis, planning, execution, documentation, memory)
+- 7 MCP resources via `repo://` URIs (architecture-map, module-index, symbol-index, test-map, doc-map, patterns, glossary)
+- Repository indexer supporting 16 programming languages
+- Keyword-based file scoring and retrieval engine (confidence 0–1)
+- Three-level verbosity system: minimal / standard / detailed
+- In-memory and file-based task memory checkpoint system
+- 55 tests across all capability modules and utilities
+- Token reduction benchmark: 97.3% average savings over direct file reading
+- CLI entry point (`engineering-mcp`) for global install and npx usage
+- Full TypeScript source with strict mode, declaration maps, and source maps
+
+### Tools
+- `task_classify` — detect task type and suggest next tools
+- `repo_scope_find` — find minimum relevant files for a task (indexes repo on first call)
+- `flow_summarize` — compact execution flow summary
+- `bug_trace_compact` — symptom-based bug cause analysis
+- `implementation_plan` — step-by-step feature/fix plan with edit targets
+- `poc_plan` — minimum viable POC scaffolding
+- `impact_analyze` — blast radius estimation before edits
+- `test_select` — minimum test set for changed files
+- `doc_context_build` — audience-targeted documentation context
+- `doc_update_plan` — identify which docs need updating
+- `memory_checkpoint` — save multi-session task state
+- `memory_restore` — restore previously saved task state

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 simpletoolsindia (support@simpletools.in)
+
+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,592 @@
+<div align="center">
+
+```
+███████╗███╗   ██╗ ██████╗ ██╗    ███╗   ███╗ ██████╗██████╗
+██╔════╝████╗  ██║██╔════╝ ██║    ████╗ ████║██╔════╝██╔══██╗
+█████╗  ██╔██╗ ██║██║  ███╗██║    ██╔████╔██║██║     ██████╔╝
+██╔══╝  ██║╚██╗██║██║   ██║██║    ██║╚██╔╝██║██║     ██╔═══╝
+███████╗██║ ╚████║╚██████╔╝██║    ██║ ╚═╝ ██║╚██████╗██║
+╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝    ╚═╝     ╚═╝ ╚═════╝╚═╝
+```
+
+**Software Engineering Intelligence — MCP Server**
+
+*Stop feeding Claude your entire codebase. Give it a brain instead.*
+
+[![npm version](https://img.shields.io/npm/v/@software-engineering/mcp-server?style=flat-square&color=cb3837&label=npm)](https://www.npmjs.com/package/@software-engineering/mcp-server)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet?style=flat-square)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-55%20passing-success?style=flat-square)](src/)
+[![Token Savings](https://img.shields.io/badge/token%20savings-97%25-ff6b35?style=flat-square)](#-proven-token-savings)
+
+</div>
+
+---
+
+## Why?
+
+Every time Claude Code helps you with a task, it reads files. Lots of them. For a 50,000-line repo, that is **hundreds of thousands of tokens per session** — slow, expensive, and wasteful.
+
+**engi-mcp** gives Claude a compact intelligence layer: indexed summaries, scoped file discovery, and compact planning tools. Instead of reading 27 files (18,000 tokens), Claude reads a 350-token summary and gets the same job done.
+
+```
+WITHOUT engi-mcp:  Claude reads 27 files  →  18,298 tokens
+WITH    engi-mcp:  3 tool calls            →     405 tokens
+                                    ─────────────────────────
+                   SAVED: 17,893 tokens  (97.8% reduction)
+```
+
+---
+
+## Table of Contents
+
+- [Quick Start](#-quick-start)
+- [How It Works](#-how-it-works)
+- [All 12 Tools](#-all-12-tools)
+- [All 7 Resources](#-all-7-resources)
+- [Proven Token Savings](#-proven-token-savings)
+- [Recommended Workflow](#-recommended-workflow)
+- [Integration with Claude Code](#-integration-with-claude-code)
+- [Architecture Deep Dive](#-architecture-deep-dive)
+- [Configuration](#-configuration)
+- [Project Structure](#-project-structure)
+- [Development](#-development)
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @software-engineering/mcp-server
+
+# Or use directly with npx (no install needed)
+npx @software-engineering/mcp-server
+```
+
+Add to your Claude Code config (~/.claude.json):
+
+```json
+{
+  "mcpServers": {
+    "engi": {
+      "command": "npx",
+      "args": ["-y", "@software-engineering/mcp-server"],
+      "env": { "LOG_LEVEL": "warn" }
+    }
+  }
+}
+```
+
+That is it. Claude now has a 97%-more-efficient brain for your repo.
+
+---
+
+## How It Works
+
+```
+Your Repo                    engi-mcp                      Claude
+    │                            │                             │
+    │  ← index on first call ────┤                             │
+    │                            │  task_classify(task) ───────┤
+    │                     detects type, suggests tools         │
+    │                            │  repo_scope_find(task) ─────┤
+    │                     ranks and returns top 5 files        │
+    │                            │  flow_summarize(files) ─────┤
+    │                     compact summary, not raw code        │
+    │                            │  implementation_plan() ─────┤
+    │                     step-by-step with edit targets       │
+    │                            │  impact_analyze() ──────────┤
+    │                     blast radius before any edit         │
+    │                            │                             │
+    │                            │ ← edit the right files only ┤
+```
+
+### Core Pipeline
+
+| Stage | What Happens |
+|-------|-------------|
+| **Index** | Scan repo once → build lightweight file/symbol/import/test/doc index |
+| **Retrieve** | Score and rank files by keyword match, export match, file type preference |
+| **Summarize** | Generate compact flow descriptions, not raw source code |
+| **Plan** | Return edit targets, risk notes, required tests — no reading needed |
+| **Memory** | Checkpoint task state so multi-session work never restarts from scratch |
+
+---
+
+## All 12 Tools
+
+### Analysis Tools
+
+#### task_classify
+Identifies what kind of task you are working on before doing any file reading.
+
+```json
+{ "task": "Fix the null pointer when user logs out" }
+```
+```json
+{
+  "types": ["bug"],
+  "confidence": 0.8,
+  "suggestedMode": "planning",
+  "nextTools": ["repo_scope_find", "implementation_plan"]
+}
+```
+
+---
+
+#### repo_scope_find
+Finds the minimum relevant files for your task. Pass repoPath the first time to build the index.
+
+```json
+{
+  "task": "Fix the null pointer when user logs out",
+  "taskType": "bug",
+  "repoPath": "/abs/path/to/your/repo",
+  "limit": 10
+}
+```
+```json
+{
+  "files": [
+    { "path": "src/auth/logout.ts", "exports": ["logout", "clearSession"] },
+    { "path": "src/auth/session.ts", "exports": ["SessionManager"] }
+  ],
+  "modules": ["auth"],
+  "symbols": ["logout", "clearSession"],
+  "confidence": 0.87
+}
+```
+
+Note: Only pass repoPath once per session. The index persists in memory.
+
+---
+
+#### flow_summarize
+Returns a compact execution flow — no raw source code.
+
+```json
+{
+  "scope": ["src/auth/logout.ts", "src/auth/session.ts"],
+  "verbosity": "standard"
+}
+```
+```json
+{
+  "summary": "2 files in flow",
+  "steps": [
+    { "order": 1, "description": "logout.ts calls clearSession() and emits event" },
+    { "order": 2, "description": "session.ts SessionManager.destroy() removes token" }
+  ],
+  "keySymbols": ["logout", "clearSession", "SessionManager"],
+  "entryPoint": "src/auth/logout.ts"
+}
+```
+
+---
+
+#### bug_trace_compact
+Analyzes a symptom description to pinpoint likely causes without reading files.
+
+```json
+{
+  "symptom": "null pointer exception when calling session.user.id after logout",
+  "scope": ["src/auth/logout.ts", "src/auth/session.ts"]
+}
+```
+```json
+{
+  "likelyCauses": [
+    { "type": "null_undefined", "description": "session.user not cleared before event fires", "likelihood": 0.85 },
+    { "type": "race_condition", "description": "async clearSession called without await", "likelihood": 0.6 }
+  ],
+  "suspectFiles": ["src/auth/session.ts"],
+  "confidence": 0.72
+}
+```
+
+---
+
+### Planning Tools
+
+#### implementation_plan
+Generates a complete step-by-step plan with exact edit targets and risk notes.
+
+```json
+{
+  "task": "Add rate limiting to the auth endpoint",
+  "taskType": "feature",
+  "scope": ["src/auth/router.ts", "src/middleware/index.ts"]
+}
+```
+```json
+{
+  "steps": [
+    { "order": 1, "description": "Add rate-limit middleware", "file": "src/middleware/rateLimit.ts", "action": "create" },
+    { "order": 2, "description": "Register middleware in router", "file": "src/auth/router.ts", "action": "modify" }
+  ],
+  "editTargets": [{ "file": "src/auth/router.ts", "description": "Add rateLimit middleware before /login handler" }],
+  "requiredTests": ["src/auth/router.test.ts"],
+  "riskNotes": ["Verify rate limit headers do not break existing auth tests"]
+}
+```
+
+---
+
+#### poc_plan
+Scaffolds a minimum viable proof-of-concept — skips production concerns deliberately.
+
+```json
+{
+  "goal": "Streaming token counter API endpoint",
+  "constraints": ["no auth", "simple"]
+}
+```
+```json
+{
+  "minimalArchitecture": "Simple Express HTTP handler with minimal routing",
+  "filesToCreate": ["src/poc/handler.ts"],
+  "shortcutsAllowed": ["Use in-memory storage", "Skip authentication"],
+  "excludedScope": ["Database integration", "Complex validation"],
+  "mockStrategy": "Use hardcoded test data and in-memory implementations"
+}
+```
+
+---
+
+### Execution Tools
+
+#### impact_analyze
+Estimates blast radius before you make any edit.
+
+```json
+{
+  "scope": ["src/core/indexer/indexer.ts"],
+  "changeType": "modify"
+}
+```
+```json
+{
+  "affectedFiles": ["src/core/retrieval/retriever.ts", "src/resources/resources.ts"],
+  "affectedModules": ["core", "resources"],
+  "regressionNotes": ["retriever depends on FileIndexEntry shape"],
+  "riskyPoints": ["RepositoryIndex interface change would cascade to all 5 consumers"],
+  "relatedTests": ["src/capabilities/analysis/analysis.test.ts"]
+}
+```
+
+---
+
+#### test_select
+Returns the minimum test set — stop running npm test when you only changed 2 files.
+
+```json
+{
+  "scope": ["src/utils/token-counter.ts"],
+  "changeType": "modify"
+}
+```
+```json
+{
+  "requiredTests": [{ "path": "src/utils/utils.test.ts", "type": "unit" }],
+  "optionalTests": [],
+  "reason": "Found 1 required and 0 optional tests for changed files"
+}
+```
+
+---
+
+### Documentation Tools
+
+#### doc_context_build
+Builds compact context for writing documentation, targeted at a specific audience.
+
+```json
+{
+  "feature": "New impact_analyze tool added to execution module",
+  "changedFiles": ["src/capabilities/execution/execution.ts"],
+  "audience": "api"
+}
+```
+
+#### doc_update_plan
+Identifies exactly which docs need updating after code changes.
+
+```json
+{
+  "changedFiles": ["src/capabilities/execution/execution.ts", "src/core/types.ts"]
+}
+```
+```json
+{
+  "docsToUpdate": [{ "path": "README.md", "reason": "References changed module: capabilities" }],
+  "sectionsToUpdate": ["README.md - capabilities section"],
+  "examplesNeeded": ["Example usage of execution"]
+}
+```
+
+---
+
+### Memory Tools
+
+#### memory_checkpoint
+Saves task state at the end of a session so the next session resumes — not restarts.
+
+```json
+{
+  "taskId": "auth-refactor-2024",
+  "taskType": "feature",
+  "files": ["src/auth/router.ts", "src/middleware/rateLimit.ts"],
+  "decisions": [{ "description": "Use token bucket algorithm", "rationale": "Simpler than sliding window for our load" }],
+  "risks": ["rate limit headers must match nginx proxy config"],
+  "notes": "Step 2/4 done. Next: add Redis backend."
+}
+```
+
+#### memory_restore
+Restores a previously saved checkpoint by taskId.
+
+```json
+{ "taskId": "auth-refactor-2024" }
+```
+```json
+{
+  "progressSummary": "1 decision recorded. 1 risk noted.",
+  "unresolvedItems": ["rate limit headers must match nginx proxy config"]
+}
+```
+
+---
+
+## All 7 Resources
+
+Resources are read via repo:// URIs — lighter than tools, no arguments needed.
+
+| Resource URI | What It Returns | Typical Use |
+|---|---|---|
+| repo://architecture-map | Module dependency graph with edge counts | Before a large refactor |
+| repo://module-index | All modules: file counts, languages, top exports | Understanding repo shape |
+| repo://symbol-index | All exported symbols (capped 200) with file + line | Finding where something lives |
+| repo://test-map | Test files to source targets mapping | Knowing test coverage at a glance |
+| repo://doc-map | Docs with sections | Finding which doc to update |
+| repo://patterns | Detected singletons, factories, handlers, schemas | Matching existing patterns |
+| repo://glossary | All module/file/symbol names | Disambiguation before searching |
+
+---
+
+## Proven Token Savings
+
+Real measurements on this repo (27 files, ~18k tokens):
+
+| Scenario | Tools Used | Without MCP | With MCP | Saved |
+|----------|-----------|------------|---------|-------|
+| Analysis | 3 | 18,298 | 405 | **97.8%** |
+| Bug Fix | 3 | 18,298 | 734 | **96.0%** |
+| Feature | 5 | 18,298 | 1,117 | **93.9%** |
+| POC | 2 | 18,298 | 128 | **99.3%** |
+| Documentation | 3 | 18,298 | 226 | **98.8%** |
+| Multi-session Memory | 2 | 36,596 | 434 | **98.8%** |
+| All 7 Resources | 7 | 18,298 | 836 | **95.4%** |
+| **TOTAL** | **19/19** | **146,384** | **3,880** | **97.3%** |
+
+Run the benchmark yourself:
+```bash
+npx tsx test-token-report.ts
+```
+
+---
+
+## Recommended Workflow
+
+Add this to your project CLAUDE.md:
+
+```
+Step 1:  task_classify(task)                 → detect type, get next tools
+Step 2:  repo_scope_find(task, repoPath)     → find minimum relevant files
+Step 3a: flow_summarize(files)               → analysis / feature
+Step 3b: bug_trace_compact(symptom, files)   → bug fix
+Step 3c: doc_context_build(feature, files)   → documentation
+Step 4a: implementation_plan(task, files)    → feature or bug
+Step 4b: poc_plan(goal)                      → proof of concept
+Step 4c: doc_update_plan(changedFiles)       → documentation
+Step 5:  impact_analyze(files, changeType)   → blast radius check
+Step 6:  test_select(files)                  → minimum test set
+Step 7:  memory_checkpoint(taskId, ...)      → save for next session
+```
+
+---
+
+## Integration with Claude Code
+
+### Option A — Global install
+
+```bash
+npm install -g @software-engineering/mcp-server
+```
+
+Add to ~/.claude.json:
+
+```json
+{
+  "mcpServers": {
+    "engi": {
+      "command": "engineering-mcp",
+      "env": { "LOG_LEVEL": "warn" }
+    }
+  }
+}
+```
+
+### Option B — npx (zero install)
+
+```json
+{
+  "mcpServers": {
+    "engi": {
+      "command": "npx",
+      "args": ["-y", "@software-engineering/mcp-server"],
+      "env": { "LOG_LEVEL": "warn" }
+    }
+  }
+}
+```
+
+### Option C — Local path
+
+```json
+{
+  "mcpServers": {
+    "engi": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-token/dist/index.js"],
+      "env": { "LOG_LEVEL": "warn" }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Config path: ~/Library/Application Support/Claude/claude_desktop_config.json
+
+```json
+{
+  "mcpServers": {
+    "engi": {
+      "command": "npx",
+      "args": ["-y", "@software-engineering/mcp-server"]
+    }
+  }
+}
+```
+
+---
+
+## Architecture Deep Dive
+
+```
+MCP Protocol (stdio)
+    ListTools / CallTool / ReadResource
+           │
+    Server (src/index.ts)
+    Tool Registry  ·  Request Routing
+      │         │         │         │         │
+  Analysis  Planning Execution   Docs    Memory
+  4 tools   2 tools  2 tools   2 tools  2 tools
+           │
+    Core Layers
+    Indexer → Retrieval Engine → Summarizer
+           │
+    Resources (repo:// URIs, 7 total)
+```
+
+### Indexer — What Gets Indexed
+
+| What | How |
+|------|-----|
+| Files | Recursive scan, skips node_modules, dist, .git, build |
+| File type | source / test / config / doc / other |
+| Language | 16 languages detected by extension |
+| Exports | Language-aware regex (TypeScript, JavaScript, Python, Go) |
+| Imports | import from, require(), from ... import |
+| Symbols | Functions, classes, interfaces, types with line numbers |
+| Tests | Files matching *.test.*, *.spec.*, __tests__/ |
+| Docs | Files matching readme, changelog, guide, api |
+
+### Retrieval — Scoring Algorithm
+
+```
+For each file in index:
+  score += 10  if keyword in file path or name
+  score += 15  if keyword in file exports
+  score += 8   if file type matches task type
+  score += 20  if doc file for documentation task
+
+confidence = avg(topN scores) / max_possible_score  →  0.0 to 1.0
+```
+
+### Verbosity Levels
+
+| Level | Tokens | Use When |
+|-------|--------|---------|
+| minimal | ~50 | Default — just key facts |
+| standard | ~150 | Exploring unfamiliar code |
+| detailed | ~400 | Debugging complex flows |
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| LOG_LEVEL | info | debug / info / warn / error |
+
+---
+
+## Project Structure
+
+```
+src/
+├── index.ts                     MCP server · tool registry · request routing
+├── bin.ts                       CLI entry (npx / global install)
+├── core/
+│   ├── types.ts                 All shared TypeScript interfaces
+│   ├── indexer/indexer.ts       Repo scanner · export parser · singleton
+│   ├── retrieval/retriever.ts   Keyword scorer · scope finder
+│   └── summarizer/summarizer.ts Flow builder · bug tracer · doc builder
+├── capabilities/
+│   ├── analysis/                task_classify · repo_scope_find · flow_summarize · bug_trace_compact
+│   ├── planning/                implementation_plan · poc_plan
+│   ├── execution/               impact_analyze · test_select
+│   ├── documentation/           doc_context_build · doc_update_plan
+│   └── memory/                  memory_checkpoint · memory_restore
+├── resources/resources.ts       7 repo:// resource builders
+├── memory/memory.ts             Checkpoint store (in-memory + file)
+└── utils/
+    ├── token-counter.ts         estimateTokens · checkTokenBudget
+    ├── logger.ts                stderr logger
+    └── formatter.ts             Response formatting
+```
+
+---
+
+## Development
+
+```bash
+npm install                      # install deps
+npm run build                    # compile TypeScript
+npm run dev                      # watch mode
+npm test                         # run 55 tests
+npx tsx test-token-report.ts     # token reduction benchmark
+```
+
+---
+
+## License
+
+MIT — see LICENSE
+
+---
+
+Made for engineers who want Claude to work smarter, not harder.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './index.js';
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,YAAY,CAAC"}

package/dist/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// CLI entry point — invoked by `engineering-mcp` or `npx @software-engineering/mcp-server`
+require("./index.js");
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";;;AACA,2FAA2F;AAC3F,sBAAoB"}