@ng-annotate/mcp-server 0.2.4 → 0.2.6

package/README.md

@@ -0,0 +1,85 @@
+# @ng-annotate/mcp-server
+
+MCP server for [ng-annotate-mcp](https://github.com/yngvebn/ngagentify) — a dev-only Angular toolchain addon that lets you annotate components in the browser and have an AI agent (Claude) act on those annotations in real time.
+
+## What this server does
+
+Exposes MCP tools that an AI agent uses to read and act on browser annotations:
+
+| Tool | Description |
+|---|---|
+| `list_sessions` | List all browser sessions |
+| `get_session` | Get a session and all its annotations |
+| `get_all_pending` | All pending annotations (sorted oldest first) |
+| `get_pending` | Pending annotations for one session |
+| `acknowledge` | Mark annotation as acknowledged (before editing files) |
+| `resolve` | Mark annotation as resolved with a summary |
+| `dismiss` | Dismiss annotation with a reason |
+| `reply` | Add a reply (for clarifications) |
+| `watch_annotations` | Long-poll (25 s) for new pending annotations |
+
+## Install
+
+```bash
+ng add @ng-annotate/angular
+```
+
+The schematic configures the MCP server automatically. For manual setup, add to `.mcp.json` (Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "ng-annotate": {
+      "command": "npx",
+      "args": ["-y", "@ng-annotate/mcp-server"],
+      "env": {
+        "NG_ANNOTATE_PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+Or `.vscode/mcp.json` (VS Code Copilot):
+
+```json
+{
+  "servers": {
+    "ng-annotate": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@ng-annotate/mcp-server"],
+      "env": {
+        "NG_ANNOTATE_PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Once the MCP server is connected, invoke the `start-polling` prompt in your AI editor:
+
+```
+/mcp ng-annotate start-polling
+```
+
+The agent will drain pending annotations, then enter a `watch_annotations` loop — processing browser annotations as they arrive and editing files automatically.
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `NG_ANNOTATE_PROJECT_ROOT` | Absolute path to the Angular project root. Used to locate the annotation store (`.ng-annotate/store.json`). |
+
+## Related packages
+
+| Package | Purpose |
+|---|---|
+| [`@ng-annotate/angular`](https://www.npmjs.com/package/@ng-annotate/angular) | Angular library (overlay UI, `provideNgAnnotate()`) |
+| [`@ng-annotate/vite-plugin`](https://www.npmjs.com/package/@ng-annotate/vite-plugin) | Vite plugin (WebSocket server, component manifest) |
+
+## License
+
+MIT

package/bin/ng-annotate-mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Entry point for the ng-annotate-mcp binary.
+// The shebang above causes npm to generate a correct Windows .cmd shim
+// that prepends `node`, rather than trying to run the .js file directly.
+import('../dist/index.js').catch(err => {
+  process.stderr.write('[ng-annotate-mcp] Fatal: ' + String(err) + '\n');
+  process.exit(1);
+});

package/dist/index.js

@@ -1,14 +1,24 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerTools } from './tools.js';
+function log(msg) {
+    process.stderr.write(`[ng-annotate-mcp] ${msg}\n`);
+}
 async function main() {
+    log(`starting up (cwd: ${process.cwd()}, node: ${process.version})`);
     const server = new McpServer({
         name: 'ng-annotate',
         version: '0.1.0',
         description: 'Connects an AI agent to a live Angular dev session for annotation-driven code changes',
     });
+    log('registering tools...');
     registerTools(server);
+    log('connecting stdio transport...');
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    log('connected — ready for requests');
 }
-main().catch(console.error);
+main().catch((err) => {
+    process.stderr.write(`[ng-annotate-mcp] fatal error: ${String(err)}\n`);
+    process.exit(1);
+});

package/dist/store.js

@@ -4,7 +4,11 @@ import { v4 as uuidv4 } from 'uuid';
 const EMPTY_STORE = { sessions: {}, annotations: {} };
 // ─── File paths ───────────────────────────────────────────────────────────────
 export const STORE_DIR = '.ng-annotate';
-export const STORE_PATH = path.join(process.cwd(), STORE_DIR, 'store.json');
+// NG_ANNOTATE_PROJECT_ROOT lets the MCP server find the store even when its
+// working directory differs from the Angular project root (e.g. when spawned
+// by VS Code Copilot or Claude Code from a non-project cwd).
+const PROJECT_ROOT = process.env.NG_ANNOTATE_PROJECT_ROOT ?? process.cwd();
+export const STORE_PATH = path.join(PROJECT_ROOT, STORE_DIR, 'store.json');
 // ─── Store init ───────────────────────────────────────────────────────────────
 export function ensureStore() {
     const dir = path.join(process.cwd(), STORE_DIR);

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@ng-annotate/mcp-server",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "bin": {
-    "ng-annotate-mcp": "dist/index.js"
+    "ng-annotate-mcp": "bin/ng-annotate-mcp.js"
   },
+  "description": "MCP server for ng-annotate-mcp — exposes Angular browser annotations as MCP tools for AI agents",
+  "keywords": [
+    "angular",
+    "mcp",
+    "mcp-server",
+    "ai",
+    "claude",
+    "devtools",
+    "ng-annotate"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/yngvebn/ngagentify"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "README.md"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",