@agentlensai/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Paz
+
+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/dist/index.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * @agentlens/mcp — MCP Server Entrypoint (Story 5.1)
+ *
+ * Starts an MCP server over stdio transport that exposes AgentLens
+ * instrumentation tools to MCP-compatible AI agents.
+ *
+ * Environment variables:
+ *   AGENTLENS_URL     — API server base URL (default: http://localhost:3400)
+ *   AGENTLENS_API_KEY — API key for authentication (optional)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { AgentLensTransport } from './transport.js';
+export { AgentLensTransport } from './transport.js';
+export { registerTools } from './tools.js';
+/**
+ * Create and configure the MCP server (exported for testing).
+ */
+export declare function createServer(): {
+    mcpServer: McpServer;
+    transport: AgentLensTransport;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,wBAAgB,YAAY,IAAI;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,CAsBtF"}

package/dist/index.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * @agentlens/mcp — MCP Server Entrypoint (Story 5.1)
+ *
+ * Starts an MCP server over stdio transport that exposes AgentLens
+ * instrumentation tools to MCP-compatible AI agents.
+ *
+ * Environment variables:
+ *   AGENTLENS_URL     — API server base URL (default: http://localhost:3400)
+ *   AGENTLENS_API_KEY — API key for authentication (optional)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { AgentLensTransport } from './transport.js';
+import { registerTools } from './tools.js';
+export { AgentLensTransport } from './transport.js';
+export { registerTools } from './tools.js';
+/**
+ * Create and configure the MCP server (exported for testing).
+ */
+export function createServer() {
+    const baseUrl = process.env['AGENTLENS_URL'] ?? 'http://localhost:3400';
+    const apiKey = process.env['AGENTLENS_API_KEY'];
+    const transport = new AgentLensTransport({ baseUrl, apiKey });
+    transport.installShutdownHandlers();
+    const mcpServer = new McpServer({
+        name: 'agentlens',
+        version: '0.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    registerTools(mcpServer, transport);
+    return { mcpServer, transport };
+}
+/**
+ * Main entry point — start the MCP server on stdio.
+ */
+async function main() {
+    const { mcpServer } = createServer();
+    const stdioTransport = new StdioServerTransport();
+    await mcpServer.connect(stdioTransport);
+    // Log to stderr so it doesn't interfere with MCP stdio protocol
+    process.stderr.write('AgentLens MCP server running\n');
+}
+// Run only when executed directly (not when imported as a library)
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+const isDirectExecution = (() => {
+    try {
+        const thisFile = fileURLToPath(import.meta.url);
+        const entryFile = process.argv[1] ? resolve(process.argv[1]) : '';
+        return thisFile === entryFile;
+    }
+    catch {
+        return false;
+    }
+})();
+if (isDirectExecution) {
+    main().catch((error) => {
+        process.stderr.write(`Fatal error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,uBAAuB,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAEhD,MAAM,SAAS,GAAG,IAAI,kBAAkB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9D,SAAS,CAAC,uBAAuB,EAAE,CAAC;IAEpC,MAAM,SAAS,GAAG,IAAI,SAAS,CAC7B;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,OAAO;KACjB,EACD;QACE,YAAY,EAAE;YACZ,KAAK,EAAE,EAAE;SACV;KACF,CACF,CAAC;IAEF,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAEpC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,EAAE,SAAS,EAAE,GAAG,YAAY,EAAE,CAAC;IAErC,MAAM,cAAc,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAClD,MAAM,SAAS,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAExC,gEAAgE;IAChE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;AACzD,CAAC;AAED,mEAAmE;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE;IAC9B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,OAAO,QAAQ,KAAK,SAAS,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC,EAAE,CAAC;AAEL,IAAI,iBAAiB,EAAE,CAAC;IACtB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/server.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server.test.d.ts.map

package/dist/server.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.test.d.ts","sourceRoot":"","sources":["../src/server.test.ts"],"names":[],"mappings":""}

package/dist/server.test.js

@@ -0,0 +1,72 @@
+/**
+ * Tests for MCP Server Entrypoint (Story 5.1)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { createServer } from './index.js';
+// Mock global fetch for the transport layer
+const mockFetch = vi.fn();
+beforeEach(() => {
+    vi.stubGlobal('fetch', mockFetch);
+    mockFetch.mockReset();
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe('MCP Server Entrypoint (Story 5.1)', () => {
+    it('creates a server with tools capability', () => {
+        const { mcpServer } = createServer();
+        expect(mcpServer).toBeDefined();
+    });
+    it('creates a transport with default URL', () => {
+        delete process.env['AGENTLENS_URL'];
+        const { transport } = createServer();
+        expect(transport).toBeDefined();
+    });
+    it('lists all 4 tools via MCP protocol', async () => {
+        const { mcpServer } = createServer();
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const client = new Client({ name: 'test-client', version: '1.0.0' });
+        await mcpServer.connect(serverTransport);
+        await client.connect(clientTransport);
+        const result = await client.listTools();
+        expect(result.tools).toHaveLength(4);
+        const names = result.tools.map((t) => t.name).sort();
+        expect(names).toEqual([
+            'agentlens_log_event',
+            'agentlens_query_events',
+            'agentlens_session_end',
+            'agentlens_session_start',
+        ]);
+    });
+    it('all tools have descriptions and input schemas', async () => {
+        const { mcpServer } = createServer();
+        const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+        const client = new Client({ name: 'test-client', version: '1.0.0' });
+        await mcpServer.connect(serverTransport);
+        await client.connect(clientTransport);
+        const result = await client.listTools();
+        for (const tool of result.tools) {
+            expect(tool.description).toBeTruthy();
+            expect(tool.inputSchema).toBeDefined();
+            expect(tool.inputSchema.type).toBe('object');
+        }
+    });
+    it('respects AGENTLENS_URL env var', () => {
+        process.env['AGENTLENS_URL'] = 'http://custom:9999';
+        const { transport } = createServer();
+        expect(transport).toBeDefined();
+        // Verify by sending an event
+        mockFetch.mockResolvedValue(new Response('{}', { status: 200, headers: { 'Content-Type': 'application/json' } }));
+        void transport.sendEventImmediate({
+            sessionId: 's',
+            agentId: 'a',
+            eventType: 'custom',
+            payload: {},
+        });
+        expect(mockFetch).toHaveBeenCalledWith('http://custom:9999/api/events', expect.anything());
+        delete process.env['AGENTLENS_URL'];
+    });
+});
+//# sourceMappingURL=server.test.js.map

package/dist/server.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.test.js","sourceRoot":"","sources":["../src/server.test.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AgentLensTransport } from './transport.js';
+/**
+ * Register all AgentLens tools on the given MCP server.
+ */
+export declare function registerTools(server: McpServer, transport: AgentLensTransport): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAIzD;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAKpF"}

package/dist/tools.js

@@ -0,0 +1,268 @@
+/**
+ * @agentlens/mcp — Tool Definitions and Handlers (Stories 5.2–5.5)
+ *
+ * Defines and registers the 4 MCP tools on an McpServer instance:
+ *  - agentlens_session_start
+ *  - agentlens_log_event
+ *  - agentlens_session_end
+ *  - agentlens_query_events
+ */
+import { z } from 'zod';
+// ─── Tool Registration ─────────────────────────────────────────────
+/**
+ * Register all AgentLens tools on the given MCP server.
+ */
+export function registerTools(server, transport) {
+    registerSessionStart(server, transport);
+    registerLogEvent(server, transport);
+    registerSessionEnd(server, transport);
+    registerQueryEvents(server, transport);
+}
+// ─── 5.2: agentlens_session_start ──────────────────────────────────
+function registerSessionStart(server, transport) {
+    server.tool('agentlens_session_start', 'Start a new AgentLens monitoring session. Returns a sessionId to use for subsequent events.', {
+        agentId: z.string().describe('Unique identifier for the agent'),
+        agentName: z.string().optional().describe('Human-readable agent name'),
+        tags: z.array(z.string()).optional().describe('Tags for categorizing this session'),
+    }, async ({ agentId, agentName, tags }) => {
+        try {
+            const sessionId = generateSessionId();
+            const event = {
+                sessionId,
+                agentId,
+                eventType: 'session_started',
+                severity: 'info',
+                payload: {
+                    agentName,
+                    tags,
+                },
+                metadata: {},
+                timestamp: new Date().toISOString(),
+            };
+            const response = await transport.sendEventImmediate(event);
+            if (!response.ok) {
+                const body = await response.text().catch(() => 'Unknown error');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error starting session: Server returned ${response.status}: ${body}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Store agentId for this session so log_event and session_end can use it
+            transport.setSessionAgent(sessionId, agentId);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ sessionId }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error starting session: ${error instanceof Error ? error.message : 'Server unreachable'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+// ─── 5.3: agentlens_log_event ──────────────────────────────────────
+function registerLogEvent(server, transport) {
+    server.tool('agentlens_log_event', 'Log an event to an active AgentLens session.', {
+        sessionId: z.string().describe('Session ID from agentlens_session_start'),
+        eventType: z.string().describe('Event type (e.g., tool_call, tool_response, custom)'),
+        payload: z
+            .record(z.unknown())
+            .describe('Event payload — structure depends on eventType'),
+        severity: z
+            .enum(['debug', 'info', 'warn', 'error', 'critical'])
+            .optional()
+            .describe('Severity level (default: info)'),
+        metadata: z
+            .record(z.unknown())
+            .optional()
+            .describe('Arbitrary metadata (tags, labels, correlation IDs)'),
+    }, async ({ sessionId, eventType, payload, severity, metadata }) => {
+        try {
+            const event = {
+                sessionId,
+                agentId: transport.getSessionAgent(sessionId),
+                eventType,
+                severity: severity ?? 'info',
+                payload,
+                metadata: metadata ?? {},
+                timestamp: new Date().toISOString(),
+            };
+            const response = await transport.sendEventImmediate(event);
+            if (!response.ok) {
+                const body = await response.text().catch(() => 'Unknown error');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error logging event: Server returned ${response.status}: ${body}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Event logged: ${eventType} (severity: ${severity ?? 'info'})`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error logging event: ${error instanceof Error ? error.message : 'Server unreachable'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+// ─── 5.4: agentlens_session_end ────────────────────────────────────
+function registerSessionEnd(server, transport) {
+    server.tool('agentlens_session_end', 'End an active AgentLens monitoring session.', {
+        sessionId: z.string().describe('Session ID to end'),
+        reason: z
+            .enum(['completed', 'error', 'timeout', 'manual'])
+            .describe('Reason for ending the session'),
+        summary: z.string().optional().describe('Optional summary of the session'),
+    }, async ({ sessionId, reason, summary }) => {
+        try {
+            const event = {
+                sessionId,
+                agentId: transport.getSessionAgent(sessionId),
+                eventType: 'session_ended',
+                severity: reason === 'error' ? 'error' : 'info',
+                payload: {
+                    reason,
+                    summary,
+                },
+                metadata: {},
+                timestamp: new Date().toISOString(),
+            };
+            // Flush any buffered events first, then send the end event
+            await transport.flush();
+            const response = await transport.sendEventImmediate(event);
+            if (!response.ok) {
+                const body = await response.text().catch(() => 'Unknown error');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error ending session: Server returned ${response.status}: ${body}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Clean up the session-agent mapping
+            transport.clearSessionAgent(sessionId);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Session ${sessionId} ended (reason: ${reason})`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error ending session: ${error instanceof Error ? error.message : 'Server unreachable'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+// ─── 5.5: agentlens_query_events ───────────────────────────────────
+function registerQueryEvents(server, transport) {
+    server.tool('agentlens_query_events', 'Query events from an AgentLens session.', {
+        sessionId: z.string().describe('Session ID to query events from'),
+        limit: z.number().optional().describe('Maximum number of events to return (default: 50)'),
+        eventType: z.string().optional().describe('Filter by event type'),
+    }, async ({ sessionId, limit, eventType }) => {
+        try {
+            const response = await transport.queryEvents({
+                sessionId,
+                limit: limit ?? 50,
+                eventType,
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => 'Unknown error');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error querying events: Server returned ${response.status}: ${body}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const data = (await response.json());
+            const events = data.events ?? [];
+            // Summarize events for the agent
+            const summaries = events.map((e) => {
+                const payloadPreview = JSON.stringify(e.payload).slice(0, 100);
+                return `[${e.timestamp}] ${e.eventType} (${e.severity}): ${payloadPreview}`;
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: events.length === 0
+                            ? 'No events found for this session.'
+                            : `Found ${events.length} event(s):\n${summaries.join('\n')}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error querying events: ${error instanceof Error ? error.message : 'Server unreachable'}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+/**
+ * Generate a simple session ID (timestamp + random suffix).
+ * The server may replace this with a ULID on ingest.
+ */
+function generateSessionId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 10);
+    return `ses_${timestamp}_${random}`;
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/tools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tools.test.d.ts.map

package/dist/tools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.test.d.ts","sourceRoot":"","sources":["../src/tools.test.ts"],"names":[],"mappings":""}