androjack-mcp 1.5.1 → 1.6.0

package/README.md

@@ -8,8 +8,9 @@
 
 ![AndroJack Banner](https://raw.githubusercontent.com/VIKAS9793/AndroJack-mcp/main/assets/AndroJack%20banner.png)
 
-### 🎬 See AndroJack in Action
+### 🎬 Discover AndroJack
 
+[![Official Product Page](https://img.shields.io/badge/Product-Landing%20Page-00C7B7?style=for-the-badge)](https://androjack-web.netlify.app/)
 [![Watch AndroJack in Action on YouTube](https://img.shields.io/badge/YouTube-Watch%20Demo-FF0000?style=for-the-badge&logo=youtube&logoColor=white)](https://youtu.be/O2aFyObV-B0)
 
 ### *An MCP server that equips your AI coding assistant with live, verified Android knowledge — so it builds from official sources, not from memory.*
@@ -17,6 +18,7 @@
 <br/>
 
 [![npm version](https://img.shields.io/npm/v/androjack-mcp?color=0A7AFF&style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/androjack-mcp)
+[![VS Code](https://img.shields.io/visual-studio-marketplace/v/VIKAS9793.androjack-vscode?color=0A7AFF&style=flat-square&logo=visual-studio-code&label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=VIKAS9793.androjack-vscode)
 [![GitHub stars](https://img.shields.io/github/stars/VIKAS9793/AndroJack-mcp?style=flat-square&logo=github&color=0A7AFF)](https://github.com/VIKAS9793/AndroJack-mcp/stargazers)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
 [![MCP Spec](https://img.shields.io/badge/MCP-2025--11--25-blueviolet?style=flat-square)](https://modelcontextprotocol.io)
@@ -27,11 +29,16 @@
 
 ### 🚀 One-Click Install
 
-[![Install in Claude Desktop](https://img.shields.io/badge/Install%20in-Claude%20Desktop-D97706?style=for-the-badge&logo=anthropic&logoColor=white)](https://claude.ai/integrations/install-mcp?params=eyJuYW1lIjoiYW5kcm9qYWNrIiwiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJhbmRyb2phY2stbWNwIl19)
-[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=androjack&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFuZHJvamFjay1tY3AiXX0=)
-[![Add to Kiro](https://img.shields.io/badge/Add%20to-AWS%20Kiro-FF9900?style=for-the-badge&logo=amazonaws&logoColor=white)](https://kiro.dev/launch/mcp/add?name=androjack&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22androjack-mcp%22%5D%7D)
+[![Install in VS Code](https://img.shields.io/badge/Install%20in-VS%20Code-007ACC?style=for-the-badge&logo=visual-studio-code&logoColor=white)](https://marketplace.visualstudio.com/items?itemName=VIKAS9793.androjack-vscode)
+[![Install in Claude Desktop](https://img.shields.io/badge/Install%20in-Claude%20Desktop-D97706?style=for-the-badge&logo=anthropic&logoColor=white)](https://claude.ai/integrations/install-mcp?params=eyJuYW1lIjoiYW5kcm9qYWNrIiwiY29tbWFuZCI6Im5weCIsImFyZ3MiOlsiLXkiLCJhbmRyb2phY2stbWNwQDEuNi4wIl19)
+[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=androjack&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImFuZHJvamFjay1tY3BAMS42LjAiXX0=)
+[![Add to Kiro](https://img.shields.io/badge/Add%20to-AWS%20Kiro-FF9900?style=for-the-badge&logo=amazonaws&logoColor=white)](https://kiro.dev/launch/mcp/add?name=androjack&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22androjack-mcp%401.6.0%22%5D%7D)
 [![View on npm](https://img.shields.io/badge/View%20on-npm-CB3837?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/androjack-mcp)
 
+**VS Code distribution:** AndroJack MCP is also live on the VS Code Marketplace as [AndroJack MCP for VS Code](https://marketplace.visualstudio.com/items?itemName=VIKAS9793.androjack-vscode). The `VS Code` badge above always reflects the currently published Marketplace version.
+
+**PM / APM docs:** Product strategy, JTBD, personas, roadmap, user stories, competitive analysis, and GTM materials now live under [product-management/README.md](product-management/README.md).
+
 <br/>
 
 **Also works with:** Windsurf · VS Code Copilot · Google Antigravity · JetBrains AI — see [Manual Config](#-manual-config--copy--paste) below ↓
@@ -487,10 +494,10 @@ Each tool lists the **specific failure mode it prevents** — not just what it d
 
 ## 🚀 Quick Start — Zero Install Required
 
-### Option 1 — Interactive CLI (v1.5.1) ✨ Recommended
+### Option 1 — Interactive CLI (v1.6.0) ✨ Recommended
 
 ```bash
-npx androjack-mcp install
+npx androjack-mcp@1.6.0 install
 ```
 
 Launches a full animated terminal wizard:
@@ -507,20 +514,20 @@ Launches a full animated terminal wizard:
 ### Option 2 — Targeted installs (non-interactive, safe in any environment)
 
 ```bash
-# Auto-detect and install to all found IDEs
-npx androjack-mcp install --auto
-
-# Install to one specific IDE
-npx androjack-mcp install --ide=cursor
-npx androjack-mcp install --ide=claude
-npx androjack-mcp install --ide=vscode
-npx androjack-mcp install --ide=windsurf
-npx androjack-mcp install --ide=jetbrains
-npx androjack-mcp install --ide=antigravity
-npx androjack-mcp install --ide=kiro
-
-# Check what's installed where
-npx androjack-mcp install --list
+# Auto-detect and install to all found IDEs
+npx androjack-mcp@1.6.0 install --auto
+
+# Install to one specific IDE
+npx androjack-mcp@1.6.0 install --ide=cursor
+npx androjack-mcp@1.6.0 install --ide=claude
+npx androjack-mcp@1.6.0 install --ide=vscode
+npx androjack-mcp@1.6.0 install --ide=windsurf
+npx androjack-mcp@1.6.0 install --ide=jetbrains
+npx androjack-mcp@1.6.0 install --ide=antigravity
+npx androjack-mcp@1.6.0 install --ide=kiro
+
+# Check what's installed where
+npx androjack-mcp@1.6.0 install --list
 ```
 
 ### Option 3 — From your IDE's NPM Scripts panel (one click)
@@ -543,7 +550,7 @@ install-mcp:list       ← see detection status
 ### Option 4 — Test all tools (no IDE needed)
 
 ```bash
-npx @modelcontextprotocol/inspector npx androjack-mcp
+npx @modelcontextprotocol/inspector npx androjack-mcp@1.6.0
 ```
 
 > **Requires:** Node.js 18+. Nothing else.
@@ -570,7 +577,7 @@ npx @modelcontextprotocol/inspector npx androjack-mcp
 
 ### AWS Kiro
 
-[![Add to Kiro](https://img.shields.io/badge/Add%20to-AWS%20Kiro-FF9900?style=for-the-badge&logo=amazonaws)](https://kiro.dev/launch/mcp/add?name=androjack&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22androjack-mcp%22%5D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
+[![Add to Kiro](https://img.shields.io/badge/Add%20to-AWS%20Kiro-FF9900?style=for-the-badge&logo=amazonaws)](https://kiro.dev/launch/mcp/add?name=androjack&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22androjack-mcp%401.6.0%22%5D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D)
 
 ---
 
@@ -584,7 +591,7 @@ npx @modelcontextprotocol/inspector npx androjack-mcp
   "mcpServers": {
     "androjack": {
       "command": "npx",
-      "args": ["-y", "androjack-mcp"],
+      "args": ["-y", "androjack-mcp@1.6.0"],
       "env": {},
       "autoApprove": [],
       "disabled": false
@@ -604,7 +611,7 @@ npx @modelcontextprotocol/inspector npx androjack-mcp
     "androjack": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "androjack-mcp"]
+      "args": ["-y", "androjack-mcp@1.6.0"]
     }
   }
 }
@@ -620,7 +627,7 @@ npx @modelcontextprotocol/inspector npx androjack-mcp
   "mcpServers": {
     "androjack": {
       "command": "npx",
-      "args": ["-y", "androjack-mcp"]
+      "args": ["-y", "androjack-mcp@1.6.0"]
     }
   }
 }
@@ -640,7 +647,7 @@ UI path: Agent pane → `...` → **MCP Servers** → **Manage MCP Servers** →
   "mcpServers": {
     "androjack": {
       "command": "npx",
-      "args": ["-y", "androjack-mcp"],
+      "args": ["-y", "androjack-mcp@1.6.0"],
       "disabled": false,
       "autoApprove": []
     }
@@ -649,13 +656,15 @@ UI path: Agent pane → `...` → **MCP Servers** → **Manage MCP Servers** →
 ```
 
 Place at `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (global).
-Or use the CLI: `kiro-cli mcp add --name androjack --command npx --args '-y androjack-mcp' --scope workspace`
+Or use the CLI: `kiro-cli mcp add --name androjack --command npx --args '-y androjack-mcp@1.6.0' --scope workspace`
 
 </details>
 
 ---
 
-## 💡 Example Session
+## 🧪 Examples
+
+### Example Session
 
 ```
 You: Build a login screen with ViewModel and Jetpack Compose
@@ -702,9 +711,9 @@ In February 2026, Google launched the Developer Knowledge MCP in public preview
 | **Mechanism** | Context Retrieval | Context Enforcement |
 | **Scope** | Generalist — Firebase, Cloud, Android, Maps, and more | Android specialist — 21 tools, one domain, zero drift |
 | **Tools** | 3 retrieval tools (`search_documents`, `get_document`, `batch_get_documents`) | 21 specialized tools — live version checks, deprecation registry, Gradle lookups, API level validation, loop-back code validator |
-| **Setup** | Google Cloud project + API key + `gcloud` CLI required | `npx androjack-mcp` — zero auth, zero cloud project |
+| **Setup** | Google Cloud project + API key + `gcloud` CLI required | `npx androjack-mcp@1.6.0` — zero auth, zero cloud project |
 | **Enforcement** | Passive — AI decides when to retrieve | Active — tool descriptions mandate calls before every task type |
-| **Status** | Public preview (v1alpha / experimental) | Stable (v1.5.1) |
+| **Status** | Public preview (v1alpha / experimental) | Stable (v1.6.0) |
 
 **Why you need both in production:**
 Google's tool cures AI "ignorance" by providing official text. However, **AndroJack cures AI "bad habits."** If you ask an AI to refactor an app, Google's tool will provide the new docs. But **AndroJack** is the tool that actively blocks the AI from writing legacy XML, enforces Jetpack Compose, checks Gradle versions against Maven, and ensures your `minSdk` doesn't violate Android 16's Play Store mandate.
@@ -713,7 +722,7 @@ Google tells the AI the rules; **AndroJack forces the AI to follow them.**
 
 ---
 
-## 🔒 Security & Privacy
+## 🔒 Security & Privacy
 
 | Property | Detail |
 |----------|--------|
@@ -721,14 +730,24 @@ Google tells the AI the rules; **AndroJack forces the AI to follow them.**
 | **Rate limiting** | 30 requests / domain / minute with exponential backoff on 429/5xx |
 | **No credentials** | Zero API keys, zero auth tokens required |
 | **No data stored** | Nothing persisted beyond process lifetime |
-| **Transparent agent** | User-Agent: `AndroJack-MCP/1.4 (documentation-grounding bot; not-a-scraper)` |
+| **Transparent agent** | User-Agent: `AndroJack-MCP/1.6.0 (documentation-grounding bot; not-a-scraper)` |
 | **Read-only** | All 21 tools are annotated `readOnlyHint: true` — no writes, no side effects |
 | **Input bounds** | All inputs length-capped and sanitized before use |
-| **Body size cap** | HTTP responses capped at 4 MB — no OOM risk on large documentation pages |
-
----
-
-## 🗺️ Knowledge Sources
+| **Body size cap** | HTTP responses capped at 4 MB — no OOM risk on large documentation pages |
+
+---
+
+## 🛡️ Privacy Policy
+
+- AndroJack runs locally in your MCP client or terminal session.
+- It does not require user accounts, API keys, or cloud credentials.
+- It does not persist prompts, source code, or tool outputs beyond the current process lifetime.
+- It only fetches from allowlisted documentation and artifact domains needed to ground answers.
+- If you run the optional HTTP mode yourself, you are responsible for your own network exposure and access controls.
+
+---
+
+## 🗺️ Knowledge Sources
 
 | Source | What It Covers |
 |--------|---------------|
@@ -742,7 +761,7 @@ Google tells the AI the rules; **AndroJack forces the AI to follow them.**
 
 ---
 
-## 🏗️ Architecture
+## 🏗️ Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -770,11 +789,21 @@ Google tells the AI the rules; **AndroJack forces the AI to follow them.**
           ▼                ▼                      ▼
   developer.android.com  kotlinlang.org    Google Maven
   issuetracker.google    source.android    Maven Central
-```
-
----
-
-## 🧑‍💻 Local Development
+```
+
+---
+
+## 🧱 Infrastructure
+
+- **Primary transport:** stdio via the `androjack-mcp` npm package for local MCP clients.
+- **Optional hosted transport:** Streamable HTTP via `node build/index.js --http` for controlled environments.
+- **Runtime model:** stateless tool execution with in-process rate limiting and shared LRU caching.
+- **Source of truth:** official Android/Kotlin docs, Google issue tracker, Google Maven, and Maven Central.
+- **Release channels:** npm for the MCP server, VS Code Marketplace for the thin wrapper that launches the pinned npm package.
+
+---
+
+## 🧑‍💻 Local Development
 
 ```bash
 git clone https://github.com/VIKAS9793/AndroJack-mcp.git
@@ -785,14 +814,38 @@ npm run inspector          # opens MCP Inspector UI
 node build/index.js        # run MCP server directly
 npm run install-mcp        # interactive installer (needs real terminal)
 npm run install-mcp:auto   # non-interactive auto-install
-npm run install-mcp:list   # check IDE detection status
-```
-
----
-
-## 📋 Changelog
-
-### v1.5.1 — Level 3 Loop-Back Validator + Interactive CLI Installer
+npm run install-mcp:list   # check IDE detection status
+```
+
+---
+
+## ❓ FAQ
+
+**Why does the VS Code extension need its own release if the MCP code lives on `main`?**  
+Because the Marketplace wrapper is a separate package. For `v1.6.0`, it is pinned to `androjack-mcp@1.6.0`, so the wrapper must be versioned and uploaded separately.
+
+**Why pin `npx -y androjack-mcp@1.6.0` instead of using the floating latest package?**  
+Pinning guarantees reproducible installs, clearer support, and predictable Anthropic or Marketplace review behavior. It avoids stale local `npx` cache surprises.
+
+**Does AndroJack send my project files to a hosted backend?**  
+No. It runs locally and only makes outbound requests to allowlisted documentation and artifact sources needed to answer the user’s query.
+
+**What should I update first for future releases?**  
+Publish the MCP server to npm first, confirm the pinned version is live, then update and upload the VS Code wrapper to point at that exact version.
+
+---
+
+## 📋 Changelog
+
+### v1.6.0 — Pinned Distribution, Shared Cache Wiring, and Registry Metadata
+
+- **New:** Exact `@1.6.0` pinning across shipped config examples, installer output, one-click install links, and the VS Code Marketplace wrapper release flow.
+- **New:** Shared fetch cache wiring for both `secureFetch()` and `secureFetchJson()` so repeated documentation and metadata lookups stop consuming rate-limit budget.
+- **New:** Official MCP registry metadata with `server.json` plus package-level `mcpName`.
+- **Fix:** User-Agent now reports the correct released version: `AndroJack-MCP/1.6.0`.
+- **Docs:** Added explicit privacy policy, infrastructure, examples, and FAQ sections for release reviewers and end users.
+
+### v1.5.1 — Level 3 Loop-Back Validator + Interactive CLI Installer
 
 - **New:** `android_code_validator` (Tool 21) — Level 3 loop-back validation gate. 24 rules across Kotlin, XML, and Gradle. Validates AI-generated code before it reaches the user. Returns PASS/WARN/FAIL verdict with line-level violations, replacements, and official doc URLs. Zero new dependencies — pure TypeScript.
 - **New:** Grounding Gate upgraded to Level 3: Step 8 mandates `android_code_validator` after every code generation. Negative constraints section lists explicit prohibitions by API level (Android 16 targets, new Compose projects, universal rules).

package/build/cache.js

@@ -1,11 +1,10 @@
 /**
- * Simple LRU cache implementation for AndroJack MCP.
+ * Shared LRU cache for AndroJack HTTP fetches and hosted-mode stats.
  */
 export class LRUCache {
     cache = new Map();
     ttlMs = 24 * 60 * 60 * 1000; // 24 hours default
     maxSize = 100;
-    // Stats
     hits = 0;
     misses = 0;
     evictions = 0;
@@ -44,7 +43,7 @@ export class LRUCache {
             this.misses++;
             return undefined;
         }
-        if (Date.now() - entry.timestamp > this.ttlMs) {
+        if (Date.now() > entry.expiresAt) {
             this.cache.delete(key);
             this.misses++;
             return undefined;
@@ -55,9 +54,11 @@ export class LRUCache {
         this.hits++;
         return entry.value;
     }
-    set(key, value) {
+    set(key, value, ttlMs = this.ttlMs) {
         if (this.ttlMs === 0)
             return;
+        if (ttlMs <= 0)
+            return;
         if (this.cache.has(key)) {
             this.cache.delete(key);
         }
@@ -69,7 +70,31 @@ export class LRUCache {
                 this.evictions++;
             }
         }
-        this.cache.set(key, { value, timestamp: Date.now() });
+        this.cache.set(key, { value, expiresAt: Date.now() + ttlMs });
+    }
+}
+const DOC_SOURCE_TTL_MS = 6 * 60 * 60 * 1000;
+const ISSUE_TRACKER_TTL_MS = 60 * 60 * 1000;
+const ARTIFACT_METADATA_TTL_MS = 30 * 60 * 1000;
+const ARTIFACT_HOSTS = new Set([
+    "dl.google.com",
+    "plugins.gradle.org",
+    "search.maven.org",
+]);
+const ISSUE_TRACKER_HOSTS = new Set([
+    "issuetracker.google.com",
+]);
+export function getFetchCacheKey(url, kind) {
+    return `${kind}:${url}`;
+}
+export function getFetchCacheTtlMs(hostname, kind) {
+    const normalized = hostname.toLowerCase();
+    if (ARTIFACT_HOSTS.has(normalized)) {
+        return ARTIFACT_METADATA_TTL_MS;
+    }
+    if (ISSUE_TRACKER_HOSTS.has(normalized)) {
+        return ISSUE_TRACKER_TTL_MS;
     }
+    return kind === "json" ? ISSUE_TRACKER_TTL_MS : DOC_SOURCE_TTL_MS;
 }
 export const docCache = new LRUCache(200);

package/build/constants.js

@@ -29,7 +29,7 @@ export const GOOGLE_MAVEN_URL = "https://dl.google.com/dl/android/maven2";
 export const JETPACK_BOM_URL = "https://developer.android.com/jetpack/compose/setup";
 // ── HTTP Client Config ──────────────────────────────────────────────────────
 export const HTTP_TIMEOUT_MS = 12_000;
-export const USER_AGENT = "AndroJack-MCP/1.0 (documentation-grounding bot; not-a-scraper)";
+export const USER_AGENT = "AndroJack-MCP/1.6.0 (documentation-grounding bot; not-a-scraper)";
 export const COMPONENT_REGISTRY = {
     // ── Deprecated concurrency ──────────────────────────────────────────────
     AsyncTask: {

package/build/http-server.js

@@ -45,12 +45,12 @@ export async function startHttpServer(server) {
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify({
                 name: "androjack-mcp",
-                version: "1.5.1",
+                version: "1.6.0",
                 description: "Documentation-grounded Android engineering MCP server. " +
                     "Forces AI tools to verify official docs before generating Android/Kotlin code.",
                 mcp_endpoint: `http://${host}:${port}${MCP_PATH}`,
                 spec_version: "2025-11-25",
-                tools: 11,
+                tools: 21,
                 read_only: true,
                 auth_required: false,
             }));

package/build/http.js

@@ -12,6 +12,7 @@
  */
 import * as cheerio from "cheerio";
 import { ALLOWED_DOMAINS, HTTP_TIMEOUT_MS, USER_AGENT } from "./constants.js";
+import { docCache, getFetchCacheKey, getFetchCacheTtlMs } from "./cache.js";
 import { logger } from "./logger.js";
 // ── Rate limiter (per domain, per process lifetime) ──────────────────────────
 const requestCounts = new Map();
@@ -90,6 +91,11 @@ async function fetchWithRetry(url, init, attempt = 0) {
 // ── Public API ────────────────────────────────────────────────────────────────
 export async function secureFetch(url) {
     const parsed = assertAllowedDomain(url);
+    const cacheKey = getFetchCacheKey(url, "html");
+    const cached = docCache.get(cacheKey);
+    if (typeof cached === "string") {
+        return cached;
+    }
     checkRateLimit(parsed.hostname);
     const response = await fetchWithRetry(url, {
         headers: {
@@ -102,17 +108,26 @@ export async function secureFetch(url) {
         throw new Error(`HTTP ${response.status} from ${parsed.hostname}: ${response.statusText}`);
     }
     const text = await response.text();
-    return text.length > MAX_BODY_BYTES ? text.slice(0, MAX_BODY_BYTES) : text;
+    const boundedText = text.length > MAX_BODY_BYTES ? text.slice(0, MAX_BODY_BYTES) : text;
+    docCache.set(cacheKey, boundedText, getFetchCacheTtlMs(parsed.hostname, "html"));
+    return boundedText;
 }
 export async function secureFetchJson(url) {
     const parsed = assertAllowedDomain(url);
+    const cacheKey = getFetchCacheKey(url, "json");
+    const cached = docCache.get(cacheKey);
+    if (cached !== undefined) {
+        return structuredClone(cached);
+    }
     checkRateLimit(parsed.hostname);
     const response = await fetchWithRetry(url, {
         headers: { "User-Agent": USER_AGENT, Accept: "application/json" },
     });
     if (!response.ok)
         throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-    return (await response.json());
+    const payload = (await response.json());
+    docCache.set(cacheKey, structuredClone(payload), getFetchCacheTtlMs(parsed.hostname, "json"));
+    return payload;
 }
 // ── HTML extraction (cheerio) ─────────────────────────────────────────────────
 export function extractPageText(html, maxChars = 3000) {

package/build/index.js

@@ -39,7 +39,7 @@ import { androidCodeValidator } from "./tools/validator.js";
 // ── Server Instantiation ────────────────────────────────────────────────────
 const server = new McpServer({
     name: "androjack-mcp",
-    version: "1.5.1",
+    version: "1.6.0",
 });
 // ── Tool 1: Official Android Documentation Search ──────────────────────────
 server.registerTool("android_official_search", {