feat(mcp): open local HTML reports

Author: New1Direction

README.md

@@ -19,10 +19,40 @@
 
 RepoLens is a **Manifest V3 Chrome extension**. Open a GitHub, GitLab, npm, or PyPI page and click the toolbar icon. RepoLens reads the repo, runs it past the AI provider you picked, and opens a tab that leads with a straight answer: should you use this? You see the verdict before any of the README's pitch.
 
+It also ships a **local MCP server** so your coding agent can scan repos before it installs or recommends a dependency. The agent gets structured JSON, and RepoLens opens a local HTML report in your browser so you still get the full visual verdict — not just a text blob.
+
 > Stars tell you a project is popular. They don't tell you whether it fits your problem. RepoLens answers the question you have: should I use this, and what am I signing up for?
 
 ---
 
+## Use RepoLens from your AI agent
+
+Run the local MCP server, then ask Claude/Cursor/Pi/etc. to use RepoLens before adding a dependency:
+
+```bash
+cd mcp
+npm install
+ANTHROPIC_API_KEY=sk-ant-... node server.js
+```
+
+Example prompts:
+
+> Use RepoLens to check whether I should use `honojs/hono` for an edge API.
+>
+> Before installing this package, run a RepoLens scan and open the report.
+>
+> Generate a RepoLens deep dive for `github.com/fastify/fastify`.
+
+MCP tools:
+
+- `scan_repo` — fast verdict-first dependency report.
+- `deep_dive` — plain-English architecture explanation with gaps/assumptions.
+- `blueprint_scene` — graph-shaped architecture map.
+
+Each tool writes a self-contained local `.html` report and opens it by default. See [`mcp/README.md`](mcp/README.md) for Claude Desktop config and environment options.
+
+---
+
 ## What you get
 
 A scan opens to a **verdict landing** and fans out into focused tabs:

mcp/README.md

@@ -1,98 +1,50 @@
 # RepoLens MCP server
 
-A local [MCP](https://modelcontextprotocol.io) server that exposes RepoLens's repo
-analysis as tools. An LLM client (Claude Desktop, Cursor, etc.) calls a tool and
-gets RepoLens's JSON back — ready to render as components.
+Let your AI agent audit dependencies before it installs or recommends them.
 
-GitHub-only, Anthropic-only, **three tools** (`scan_repo`, `blueprint_scene`,
-`deep_dive`). Each reuses the extension's own pipeline modules verbatim
-(`fetcher.js`, `prompt.js`, `parser.js`, `deepdive.js`, `blueprint-adapter.js`);
-only the provider call (`anthropic.js`) is MCP-specific.
+RepoLens MCP runs locally over stdio. Your agent gets structured JSON, and the MCP
+server also writes a self-contained **local HTML report** and opens it in your
+browser by default — so users get the full RepoLens visual verdict, not just a
+block of text in chat.
 
-## What stays true
+## Why agents need this
 
-- **Local only.** Runs over stdio, spawned by your client. No hosted backend.
-- **Bring your own key.** The Anthropic key comes from the environment, never from
-  a server or the extension's storage. Nothing phones home.
+Coding agents constantly choose packages from README text, stars, or stale blog
+posts. RepoLens gives the agent a dependency due-diligence tool:
 
-## Tools
-
-### `scan_repo({ repo })`
-
-`repo` is `owner/name` or a GitHub URL. Returns the analysis JSON:
-
-```json
-{
-  "repoId": "honojs/hono",
-  "platform": "github",
-  "language": "TypeScript",
-  "license": "MIT",
-  "stars": 21000,
-  "description": "Small, fast web framework for the edges.",
-  "fit": { "level": "strong", "label": "Strong fit", "why": "Health 92 · 0 flags · 4 pros / 1 cons" },
-  "bottom_line": "A lean, fast framework worth adopting for edge runtimes.",
-  "health": { "score": 92 },
-  "pros": ["..."],
-  "cons": ["..."],
-  "red_flags": [],
-  "capabilities": ["routing", "middleware", "edge"]
-}
-```
+> “Should I use this repo, what are the risks, and what should I try first?”
 
-`fit` is derived deterministically from the health score, red-flag count, and
-pros/cons balance — `level` is one of `strong | solid | care | risky`.
+## Tools
 
-### `blueprint_scene({ repo })`
+- `scan_repo` — verdict-first report: fit, health, pros, cons, red flags,
+  capabilities, bottom line.
+- `deep_dive` — plain-English architecture explanation, weak spots, assumptions,
+  self-test questions, atoms + lineage.
+- `blueprint_scene` — graph-shaped architecture map with nodes/edges/positions.
 
-Maps how the repo is built and returns a laid-out scene — `nodes` (key parts) and
-`edges` (how they relate), with positions — ready for a `<DependencyGraph>`-style
-component. Heavier than `scan_repo`: it reads source and makes two model calls
-(atoms, then lineage). Edges are engine-shaped (`{ id, from, to, rel }`), not
-`{ source, target }`.
+Every tool accepts:
 
 ```json
 {
-  "id": "repo:...",
-  "scope": "blueprint",
-  "repoId": "honojs/hono",
-  "nodes": [
-    {
-      "id": "app",
-      "label": "Hono app",
-      "kind": "entrypoint",
-      "x": 120,
-      "y": 40,
-      "layer": "entrypoint",
-      "ref": { "root": true, "purpose": "...", "files": ["src/hono.ts"] }
-    }
-  ],
-  "edges": [{ "id": "e123", "from": "app", "to": "router", "rel": "depends-on" }],
-  "camera": { "x": 0, "y": 0, "zoom": 1 }
+  "repo": "honojs/hono",
+  "report": true,
+  "openReport": true
 }
 ```
 
-### `deep_dive({ repo })`
+- `report` defaults to `true` and writes a local `.html` file.
+- `openReport` defaults to `true` and opens that file in the browser.
+- Set `openReport: false` if the agent should only return the report path.
+- Set `report: false` for pure JSON/tool-only usage.
 
-Explains how the repo actually works in plain language, with the weak spots named.
-Returns a from-scratch `explanation`, the `gaps` and `assumptions` behind it,
-self-test `questions`, per-claim `confidence`, plus the underlying `atoms` and
-`lineage`. **Heaviest tool** — reads source and makes three model calls
-(atoms → lineage → Feynman).
+The returned JSON includes:
 
 ```json
 {
-  "repoId": "honojs/hono",
-  "degraded": false,
-  "explanation": "Hono is a small web framework that ...",
-  "gaps": ["..."],
-  "assumptions": ["..."],
-  "questions": [{ "q": "What runs a request?", "a": "..." }],
-  "confidence": [{ "claim": "...", "level": "high", "note": "..." }],
-  "atoms": [{ "id": "router", "name": "Router", "kind": "subsystem", "purpose": "..." }],
-  "lineage": {
-    "links": [{ "from": "app", "to": "router", "relation": "depends-on" }],
-    "roots": ["app"],
-    "leaves": []
+  "report": {
+    "path": "/tmp/repolens-mcp-reports/honojs-hono-scan_repo-....html",
+    "url": "file:///tmp/repolens-mcp-reports/honojs-hono-scan_repo-....html",
+    "opened": true
   }
 }
 ```
@@ -109,31 +61,60 @@ export GITHUB_TOKEN=ghp_...               # optional; lifts GitHub 60/hr → 500
 node server.js                            # speaks MCP over stdio
 ```
 
-A `GITHUB_TOKEN` is **strongly recommended** for `blueprint_scene` and `deep_dive`:
-each makes 10+ GitHub calls per run and will hit the 60 req/hr anonymous limit
-(surfacing as a mid-scan `GitHub 403`) without one.
+Optional report environment variables:
+
+```bash
+export REPOLENS_MCP_OPEN_REPORT=0          # never auto-open reports
+export REPOLENS_MCP_REPORT_DIR=/tmp/reports # custom report directory
+```
+
+A `GITHUB_TOKEN` is strongly recommended for `blueprint_scene` and `deep_dive`:
+each makes multiple GitHub calls and anonymous GitHub API limits are low.
 
-### Add to Claude Desktop
+## Claude Desktop config
 
-In `claude_desktop_config.json`:
+Add this to `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "repolens": {
       "command": "node",
       "args": ["/absolute/path/to/repolens/mcp/server.js"],
-      "env": { "ANTHROPIC_API_KEY": "sk-ant-...", "GITHUB_TOKEN": "ghp_..." }
+      "env": {
+        "ANTHROPIC_API_KEY": "sk-ant-...",
+        "GITHUB_TOKEN": "ghp_..."
+      }
     }
   }
 }
 ```
 
-## Notes
+## Example prompts
+
+```text
+Use RepoLens to check whether I should use honojs/hono for an edge API.
+```
+
+```text
+Before you add this dependency, run RepoLens scan_repo and open the report.
+```
+
+```text
+Generate a RepoLens deep_dive for github.com/fastify/fastify and summarize the gaps.
+```
+
+```text
+Use blueprint_scene on remix-run/remix so I can see how the repo is structured.
+```
+
+## Current scope
+
+- GitHub input only: `owner/name` or a GitHub URL.
+- Anthropic provider only via `ANTHROPIC_API_KEY`.
+- Local-only: no hosted backend, no RepoLens account.
+- The Chrome extension still has the broader provider/platform UX; MCP is the
+  agent-native path.
 
-- `deep_dive` and `blueprint_scene` are GitHub-deep but README-shallow elsewhere:
-  only GitHub exposes a file tree, so on other platforms they degrade (`deep_dive`
-  sets `degraded: true`).
-- Next (follow-ups): multi-provider (reuse the extension's `providers.js` registry),
-  npm / PyPI / GitLab inputs for `scan_repo` (the fetcher already supports them —
-  only the input parser is GitHub-only), and a `tools/list` structural smoke test.
+Planned next steps: publish as `repolens-mcp`, add OpenAI/OpenRouter/Gemini env
+providers, and extend `scan_repo` to npm/PyPI/GitLab inputs.

mcp/blueprint-scene.js

@@ -19,6 +19,7 @@ import { buildBlueprintScene } from '../src/blueprint-adapter.js';
 import { parseRepoInput } from './repo-input.js';
 import { callAnthropic } from './anthropic.js';
 import { ghOpts } from './github-auth.js';
+import { attachHtmlReport } from './report.js';
 
 export const BLUEPRINT_TOOL = {
   name: 'blueprint_scene',
@@ -28,7 +29,14 @@ export const BLUEPRINT_TOOL = {
     'dependency / architecture diagram. Heavier than scan_repo (reads source, two model calls).',
   inputSchema: {
     type: 'object',
-    properties: { repo: { type: 'string', description: 'A repo as owner/name or a GitHub URL' } },
+    properties: {
+      repo: { type: 'string', description: 'A repo as owner/name or a GitHub URL' },
+      report: { type: 'boolean', description: 'Write a local HTML report. Default: true.' },
+      openReport: {
+        type: 'boolean',
+        description: 'Open the local HTML report in the browser. Default: true.',
+      },
+    },
     required: ['repo'],
     additionalProperties: false,
   },
@@ -87,6 +95,11 @@ export const BLUEPRINT_TOOL = {
         properties: { x: { type: 'number' }, y: { type: 'number' }, zoom: { type: 'number' } },
       },
       source: { type: 'object', description: 'lens + timestamps' },
+      report: {
+        type: 'object',
+        description: 'Local HTML report path/url opened for the user.',
+        properties: { path: { type: 'string' }, url: { type: 'string' }, opened: { type: 'boolean' } },
+      },
     },
     required: ['id', 'nodes', 'edges'],
   },
@@ -99,5 +112,6 @@ export async function runBlueprintScene(args) {
   const source = await fetchSource(platform, repoId, opts);
   const { atoms } = parseAtoms(await callAnthropic(buildAtomsPrompt(repoData, source, null)));
   const lineage = parseLineage(await callAnthropic(buildLineagePrompt(atoms)));
-  return buildBlueprintScene({ deepDive: { atoms, lineage }, repoId, title: repoId });
+  const result = buildBlueprintScene({ deepDive: { atoms, lineage }, repoId, title: repoId });
+  return attachHtmlReport('blueprint_scene', repoId, result, args);
 }

mcp/deep-dive.js

@@ -20,6 +20,7 @@ import {
 import { parseRepoInput } from './repo-input.js';
 import { callAnthropic } from './anthropic.js';
 import { ghOpts } from './github-auth.js';
+import { attachHtmlReport } from './report.js';
 
 export const DEEP_DIVE_TOOL = {
   name: 'deep_dive',
@@ -30,7 +31,14 @@ export const DEEP_DIVE_TOOL = {
     'wants to *understand* a codebase, not just judge it. Heaviest tool (reads source, three model calls).',
   inputSchema: {
     type: 'object',
-    properties: { repo: { type: 'string', description: 'A repo as owner/name or a GitHub URL' } },
+    properties: {
+      repo: { type: 'string', description: 'A repo as owner/name or a GitHub URL' },
+      report: { type: 'boolean', description: 'Write a local HTML report. Default: true.' },
+      openReport: {
+        type: 'boolean',
+        description: 'Open the local HTML report in the browser. Default: true.',
+      },
+    },
     required: ['repo'],
     additionalProperties: false,
   },
@@ -67,6 +75,11 @@ export const DEEP_DIVE_TOOL = {
       },
       atoms: { type: 'array', description: 'The atomic units the explanation is built from.' },
       lineage: { type: 'object', description: 'Causal links + roots/leaves between atoms.' },
+      report: {
+        type: 'object',
+        description: 'Local HTML report path/url opened for the user.',
+        properties: { path: { type: 'string' }, url: { type: 'string' }, opened: { type: 'boolean' } },
+      },
     },
     required: ['repoId', 'explanation'],
   },
@@ -95,5 +108,6 @@ export async function runDeepDive(args) {
   const { atoms } = parseAtoms(await callAnthropic(buildAtomsPrompt(repoData, source, null)));
   const lineage = parseLineage(await callAnthropic(buildLineagePrompt(atoms)));
   const feynman = parseFeynman(await callAnthropic(buildFeynmanPrompt(repoData, atoms, lineage)));
-  return buildDeepDiveResult(repoId, atoms, lineage, feynman, source);
+  const result = buildDeepDiveResult(repoId, atoms, lineage, feynman, source);
+  return attachHtmlReport('deep_dive', repoId, result, args);
 }

mcp/package.json

@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
-  "description": "Local MCP server exposing RepoLens repo analysis (scan_repo) as a tool.",
+  "description": "Local MCP server that lets agents scan repos and opens RepoLens HTML reports.",
   "bin": {
     "repolens-mcp": "./server.js"
   },