@ng-annotate/mcp-server 0.2.1

package/dist/mcp-server/src/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mcp-server/src/index.js

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.js';
+async function main() {
+    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',
+    });
+    registerTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/mcp-server/src/tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTools(server: McpServer): void;

package/dist/mcp-server/src/tools.js

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { store } from '../../vite-plugin/src/store.js';
+// ─── Response helpers ─────────────────────────────────────────────────────────
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function error(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_WATCH_TIMEOUT_MS = 25000;
+const WATCH_POLL_INTERVAL_MS = 500;
+// ─── Work loop prompt ─────────────────────────────────────────────────────────
+const WORK_LOOP_PROMPT = `\
+Start the ng-annotate annotation work loop. Follow these steps continuously until told to stop.
+
+## Startup
+1. Call \`get_all_pending\` to drain any annotations that arrived before you connected.
+2. Process each pending annotation (see Processing below).
+
+## Watch loop
+3. Call \`watch_annotations\` (default timeout).
+4. If it returns \`{"status":"annotations",...}\`: process each annotation in the list.
+5. If it returns \`{"status":"timeout"}\`: call \`watch_annotations\` again immediately.
+6. After processing, return to step 3.
+
+## Processing an annotation
+1. Call \`acknowledge\` with the annotation ID — immediately, before reading any files.
+2. Read \`componentFilePath\` and (if present) \`templateFilePath\` from the annotation data.
+3. Understand the intent: \`annotationText\` is the instruction; \`selectionText\` is the highlighted target (prefer this as the primary focus when present).
+4. Edit the component template, TypeScript, or SCSS as needed. Make minimal, targeted changes — do not refactor surrounding code.
+5. If the template change also requires a TypeScript change (e.g. adding a property), make both.
+6. Once the change is written to disk: call \`resolve\` with a one-sentence summary.
+7. If you need clarification: call \`reply\` with a question. Do NOT resolve yet.
+8. If the request is out of scope or not actionable: call \`dismiss\` with a reason.
+
+## Rules
+- Always \`acknowledge\` before touching any files.
+- Never modify files without a corresponding annotation.
+- Never \`resolve\` until the change is actually written to disk.
+`;
+// ─── Tool and prompt registration ─────────────────────────────────────────────
+export function registerTools(server) {
+    // ── Prompt ────────────────────────────────────────────────────────────────
+    server.registerPrompt('start-polling', {
+        description: 'Start the ng-annotate annotation watch loop. Injects the full work loop instructions into the conversation.',
+    }, () => ({
+        messages: [{ role: 'user', content: { type: 'text', text: WORK_LOOP_PROMPT } }],
+    }));
+    // ── Session tools ─────────────────────────────────────────────────────────
+    server.registerTool('list_sessions', { description: 'List all browser sessions connected to the dev server' }, async () => {
+        const sessions = await store.listSessions();
+        return json(sessions);
+    });
+    server.registerTool('get_session', {
+        description: 'Get a session and all its annotations',
+        inputSchema: { id: z.string().describe('Session ID') },
+    }, async ({ id }) => {
+        const session = await store.getSession(id);
+        if (!session)
+            return error(`Session not found: ${id}`);
+        const annotations = await store.listAnnotations(id);
+        return json({ session, annotations });
+    });
+    // ── Query tools ───────────────────────────────────────────────────────────
+    server.registerTool('get_pending', {
+        description: 'Get all pending annotations for a specific session',
+        inputSchema: { sessionId: z.string().describe('Session ID') },
+    }, async ({ sessionId }) => {
+        const annotations = await store.listAnnotations(sessionId, 'pending');
+        return json(annotations);
+    });
+    server.registerTool('get_all_pending', {
+        description: 'Startup step: get all pending annotations across all sessions, sorted oldest first. Call this on startup to drain annotations that arrived before the agent connected, then enter the watch_annotations loop.',
+    }, async () => {
+        const annotations = await store.listAnnotations(undefined, 'pending');
+        return json(annotations);
+    });
+    // ── Action tools ──────────────────────────────────────────────────────────
+    server.registerTool('acknowledge', {
+        description: "Acknowledge a pending annotation (pending → acknowledged). Call this IMMEDIATELY after receiving an annotation and BEFORE reading any files or starting edits. This signals to the browser that the agent is working on it.",
+        inputSchema: {
+            id: z.string().describe('Annotation ID'),
+            message: z.string().optional().describe('Optional message to add as a reply'),
+        },
+    }, async ({ id, message }) => {
+        const annotation = await store.getAnnotation(id);
+        if (!annotation)
+            return error(`Annotation not found: ${id}`);
+        if (annotation.status === 'acknowledged')
+            return error(`Annotation ${id} is already acknowledged`);
+        const updated = await store.updateAnnotation(id, { status: 'acknowledged' });
+        if (!updated)
+            return error(`Failed to update annotation: ${id}`);
+        if (message) {
+            await store.addReply(id, { author: 'agent', message });
+        }
+        return json(updated);
+    });
+    server.registerTool('resolve', {
+        description: 'Mark an annotation as resolved. Call this ONLY after the file change has been successfully written to disk. Include a one-sentence summary of what was changed.',
+        inputSchema: {
+            id: z.string().describe('Annotation ID'),
+            summary: z.string().optional().describe('One-sentence summary of what was changed'),
+        },
+    }, async ({ id, summary }) => {
+        const annotation = await store.getAnnotation(id);
+        if (!annotation)
+            return error(`Annotation not found: ${id}`);
+        const updated = await store.updateAnnotation(id, { status: 'resolved' });
+        if (!updated)
+            return error(`Failed to update annotation: ${id}`);
+        if (summary) {
+            await store.addReply(id, { author: 'agent', message: summary });
+        }
+        return json(updated);
+    });
+    server.registerTool('dismiss', {
+        description: 'Dismiss an annotation as not actionable. Use when the request is out of scope, contradicts existing code, or cannot be safely implemented. A reason is required.',
+        inputSchema: {
+            id: z.string().describe('Annotation ID'),
+            reason: z.string().describe('Reason for dismissal (required)'),
+        },
+    }, async ({ id, reason }) => {
+        if (!reason)
+            return error('Reason is required for dismissal');
+        const annotation = await store.getAnnotation(id);
+        if (!annotation)
+            return error(`Annotation not found: ${id}`);
+        const updated = await store.updateAnnotation(id, { status: 'dismissed' });
+        if (!updated)
+            return error(`Failed to update annotation: ${id}`);
+        await store.addReply(id, { author: 'agent', message: reason });
+        return json(updated);
+    });
+    server.registerTool('reply', {
+        description: 'Add an agent reply to an annotation thread without resolving it. Use to ask for clarification when the request is ambiguous. Do NOT call resolve until the user has responded.',
+        inputSchema: {
+            id: z.string().describe('Annotation ID'),
+            message: z.string().describe('Reply message'),
+        },
+    }, async ({ id, message }) => {
+        const annotation = await store.getAnnotation(id);
+        if (!annotation)
+            return error(`Annotation not found: ${id}`);
+        const updated = await store.addReply(id, { author: 'agent', message });
+        if (!updated)
+            return error(`Failed to add reply to annotation: ${id}`);
+        return json(updated);
+    });
+    // ── Watch tool ────────────────────────────────────────────────────────────
+    server.registerTool('watch_annotations', {
+        description: `Long-poll for new pending annotations (polls every 500ms, default ${String(DEFAULT_WATCH_TIMEOUT_MS / 1000)}s timeout). Returns immediately if pending annotations already exist. This is the main event loop — call it again after processing annotations or on timeout, and keep calling it indefinitely. Result shape: {"status":"annotations","annotations":[...]} or {"status":"timeout"}.`,
+        inputSchema: {
+            sessionId: z.string().optional().describe('Optional session ID to filter by'),
+            timeoutMs: z
+                .number()
+                .optional()
+                .describe(`Timeout in milliseconds (default: ${String(DEFAULT_WATCH_TIMEOUT_MS)})`),
+        },
+    }, async ({ sessionId, timeoutMs }) => {
+        const timeout = timeoutMs ?? DEFAULT_WATCH_TIMEOUT_MS;
+        // Check immediately first
+        const existing = await store.listAnnotations(sessionId, 'pending');
+        if (existing.length > 0) {
+            return json({ status: 'annotations', annotations: existing });
+        }
+        // Poll for the duration of timeout
+        const result = await new Promise((resolve) => {
+            const interval = setInterval(() => {
+                void (async () => {
+                    const pending = await store.listAnnotations(sessionId, 'pending');
+                    if (pending.length > 0) {
+                        clearInterval(interval);
+                        clearTimeout(timer);
+                        resolve({ status: 'annotations', annotations: pending });
+                    }
+                })();
+            }, WATCH_POLL_INTERVAL_MS);
+            const timer = setTimeout(() => {
+                clearInterval(interval);
+                resolve({ status: 'timeout' });
+            }, timeout);
+        });
+        return json(result);
+    });
+}

package/dist/vite-plugin/src/store.d.ts

@@ -0,0 +1,47 @@
+export type AnnotationStatus = 'pending' | 'acknowledged' | 'resolved' | 'dismissed';
+export interface Session {
+    id: string;
+    createdAt: string;
+    lastSeenAt: string;
+    active: boolean;
+    url: string;
+}
+export interface AnnotationReply {
+    id: string;
+    createdAt: string;
+    author: 'agent' | 'user';
+    message: string;
+}
+export interface Annotation {
+    id: string;
+    sessionId: string;
+    createdAt: string;
+    status: AnnotationStatus;
+    replies: AnnotationReply[];
+    componentName: string;
+    componentFilePath: string;
+    templateFilePath?: string;
+    selector: string;
+    inputs: Record<string, unknown>;
+    domSnapshot: string;
+    componentTreePath: string[];
+    annotationText: string;
+    selectionText?: string;
+}
+export declare const STORE_DIR = ".ng-annotate";
+export declare const STORE_PATH: string;
+export declare function ensureStore(): void;
+type WatcherFn = (annotation: Annotation) => void;
+export declare function addWatcher(fn: WatcherFn): () => void;
+export declare const store: {
+    createSession(payload: Omit<Session, "id" | "createdAt" | "lastSeenAt">): Promise<Session>;
+    updateSession(id: string, patch: Partial<Session>): Promise<Session | undefined>;
+    listSessions(): Promise<Session[]>;
+    getSession(id: string): Promise<Session | undefined>;
+    createAnnotation(payload: Omit<Annotation, "id" | "createdAt" | "status" | "replies">): Promise<Annotation>;
+    getAnnotation(id: string): Promise<Annotation | undefined>;
+    listAnnotations(sessionId?: string, status?: AnnotationStatus): Promise<Annotation[]>;
+    updateAnnotation(id: string, patch: Partial<Annotation>): Promise<Annotation | undefined>;
+    addReply(annotationId: string, reply: Omit<AnnotationReply, "id" | "createdAt">): Promise<Annotation | undefined>;
+};
+export {};

package/dist/vite-plugin/src/store.js

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+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');
+// ─── Store init ───────────────────────────────────────────────────────────────
+export function ensureStore() {
+    const dir = path.join(process.cwd(), STORE_DIR);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    if (!fs.existsSync(STORE_PATH)) {
+        fs.writeFileSync(STORE_PATH, JSON.stringify(EMPTY_STORE, null, 2), 'utf8');
+    }
+}
+// ─── File locking ─────────────────────────────────────────────────────────────
+// In-process mutex: serializes all writes from the same process using a promise chain.
+// writeQueue always resolves (never rejects) so the chain is never broken by a
+// failing task. The Promise returned to the caller still rejects on error.
+// Note: cross-process safety (Vite plugin + MCP server) can be layered on top
+// via proper-lockfile if needed, but requires a platform-reliable approach.
+let writeQueue = Promise.resolve();
+async function withLock(fn) {
+    ensureStore();
+    const result = writeQueue.then(async () => {
+        const raw = fs.readFileSync(STORE_PATH, 'utf8');
+        const data = JSON.parse(raw);
+        const updated = await fn(data);
+        fs.writeFileSync(STORE_PATH, JSON.stringify(updated, null, 2), 'utf8');
+        return updated;
+    });
+    // Keep the queue alive even when this task fails
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    writeQueue = result.catch(() => { });
+    return result;
+}
+function readStore() {
+    ensureStore();
+    return JSON.parse(fs.readFileSync(STORE_PATH, 'utf8'));
+}
+const watchers = new Set();
+export function addWatcher(fn) {
+    watchers.add(fn);
+    return () => watchers.delete(fn);
+}
+function notifyWatchers(annotation) {
+    for (const fn of watchers)
+        fn(annotation);
+}
+// ─── Store API ────────────────────────────────────────────────────────────────
+export const store = {
+    async createSession(payload) {
+        const now = new Date().toISOString();
+        const session = {
+            id: uuidv4(),
+            createdAt: now,
+            lastSeenAt: now,
+            ...payload,
+        };
+        await withLock((data) => {
+            data.sessions[session.id] = session;
+            return data;
+        });
+        return session;
+    },
+    async updateSession(id, patch) {
+        let result;
+        await withLock((data) => {
+            const existing = data.sessions[id];
+            if (!existing)
+                return data;
+            const updated = { ...existing, ...patch, id };
+            data.sessions[id] = updated;
+            result = updated;
+            return data;
+        });
+        return result;
+    },
+    listSessions() {
+        const data = readStore();
+        return Promise.resolve(Object.values(data.sessions).filter((s) => s !== undefined));
+    },
+    getSession(id) {
+        const data = readStore();
+        return Promise.resolve(data.sessions[id]);
+    },
+    async createAnnotation(payload) {
+        const annotation = {
+            id: uuidv4(),
+            createdAt: new Date().toISOString(),
+            status: 'pending',
+            replies: [],
+            ...payload,
+        };
+        await withLock((data) => {
+            data.annotations[annotation.id] = annotation;
+            return data;
+        });
+        notifyWatchers(annotation);
+        return annotation;
+    },
+    getAnnotation(id) {
+        const data = readStore();
+        return Promise.resolve(data.annotations[id]);
+    },
+    listAnnotations(sessionId, status) {
+        const data = readStore();
+        let list = Object.values(data.annotations).filter((a) => a !== undefined);
+        if (sessionId)
+            list = list.filter((a) => a.sessionId === sessionId);
+        if (status)
+            list = list.filter((a) => a.status === status);
+        return Promise.resolve(list.sort((a, b) => a.createdAt.localeCompare(b.createdAt)));
+    },
+    async updateAnnotation(id, patch) {
+        let result;
+        await withLock((data) => {
+            const existing = data.annotations[id];
+            if (!existing)
+                return data;
+            const updated = { ...existing, ...patch, id };
+            data.annotations[id] = updated;
+            result = updated;
+            return data;
+        });
+        return result;
+    },
+    async addReply(annotationId, reply) {
+        let result;
+        await withLock((data) => {
+            const annotation = data.annotations[annotationId];
+            if (!annotation)
+                return data;
+            const newReply = {
+                id: uuidv4(),
+                createdAt: new Date().toISOString(),
+                ...reply,
+            };
+            annotation.replies.push(newReply);
+            result = annotation;
+            return data;
+        });
+        return result;
+    },
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ng-annotate/mcp-server",
+  "version": "0.2.1",
+  "type": "module",
+  "bin": {
+    "ng-annotate-mcp": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yngvebn/ngagentify"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "~5.6.0",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  }
+}