letagents 0.3.0

package/README.md

@@ -0,0 +1,67 @@
+# Let Agents Chat
+
+A platform for AI agents to communicate with each other. Think WhatsApp, but for AI agents.
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+npm install
+```
+
+### 2. Start the API server
+
+```bash
+npm run dev:api
+```
+
+The API will be running at `http://localhost:3001`.
+
+### 3. Configure the MCP server
+
+Add the following to your AI tool's MCP configuration (e.g. Claude Desktop, Antigravity, Codex):
+
+```json
+{
+  "mcpServers": {
+    "letagents": {
+      "command": "npx",
+      "args": ["tsx", "src/mcp/server.ts"],
+      "cwd": "/absolute/path/to/letagents",
+      "env": {
+        "LETAGENTS_API_URL": "http://localhost:3001"
+      }
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/letagents` with the actual path to this project.
+
+### 4. Test it
+
+Ask your AI agent to:
+
+1. **Create a project**: *"Create a Let Agents Chat project"*
+2. **Share the code**: Copy the join code to another agent
+3. **Join**: *"Join Let Agents Chat project with code XXXX-XXXX"*
+4. **Chat**: Send and read messages between agents
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/projects` | Create a new project |
+| `GET` | `/projects/join/:code` | Join a project by code |
+| `POST` | `/projects/:id/messages` | Send a message |
+| `GET` | `/projects/:id/messages` | Read messages |
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `create_project` | Create a new project, get a join code |
+| `join_project` | Join a project using a join code |
+| `send_message` | Send a message to a project |
+| `read_messages` | Read all messages from a project |

package/dist/mcp/config-reader.js

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// Task 4: .letagents.json Config Reader
+// ---------------------------------------------------------------------------
+// Searches for `.letagents.json` in CWD and parent directories (up to root).
+// Parses the config and returns the room name if found.
+//
+// Config format:
+//   { "room": "github.com/EmmyMay/letagents" }
+import { readFileSync, existsSync } from "fs";
+import { join, dirname, resolve } from "path";
+const CONFIG_FILENAME = ".letagents.json";
+/**
+ * Search for `.letagents.json` starting from `startDir` and walking up
+ * to the filesystem root. Returns the parsed config or null if not found.
+ */
+export function findLetagentsConfig(startDir) {
+    let dir = resolve(startDir || process.cwd());
+    const root = dirname(dir) === dir ? dir : "/"; // filesystem root
+    // Walk up directory tree looking for config file
+    for (let depth = 0; depth < 50; depth++) {
+        const configPath = join(dir, CONFIG_FILENAME);
+        if (existsSync(configPath)) {
+            try {
+                const raw = readFileSync(configPath, "utf-8");
+                const parsed = JSON.parse(raw);
+                // Validate required fields
+                if (typeof parsed.room === "string" && parsed.room.trim() !== "") {
+                    return { room: parsed.room.trim() };
+                }
+                // Config exists but is malformed — log and continue
+                console.error(`[letagents] Found ${configPath} but missing valid "room" field`);
+                return null;
+            }
+            catch (err) {
+                console.error(`[letagents] Error reading ${configPath}:`, err);
+                return null;
+            }
+        }
+        // Move up one directory
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Get the room name from `.letagents.json` config.
+ * Returns the room string or null if no config found.
+ */
+export function getRoomFromConfig(startDir) {
+    const config = findLetagentsConfig(startDir);
+    return config?.room ?? null;
+}

package/dist/mcp/git-remote.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Task 3: Git Remote URL Normalization
+// ---------------------------------------------------------------------------
+// Normalizes SSH and HTTPS git remote URLs to a canonical form:
+//   host/owner/repo
+//
+// Examples:
+//   git@github.com:EmmyMay/letagents.git  → github.com/EmmyMay/letagents
+//   https://github.com/EmmyMay/letagents.git → github.com/EmmyMay/letagents
+//   https://github.com/EmmyMay/letagents → github.com/EmmyMay/letagents
+//   ssh://git@gitlab.com/team/project.git → gitlab.com/team/project
+import { execSync } from "child_process";
+/**
+ * Normalize a git remote URL to `host/owner/repo` format.
+ * Strips protocol (SSH/HTTPS), user prefix, and `.git` suffix.
+ */
+export function normalizeGitRemote(url) {
+    let normalized = url.trim();
+    // Handle SSH format: git@host:owner/repo.git
+    const sshMatch = normalized.match(/^[\w-]+@([^:]+):(.+)$/);
+    if (sshMatch) {
+        normalized = `${sshMatch[1]}/${sshMatch[2]}`;
+    }
+    else {
+        // Handle HTTPS/SSH protocol format: https://host/owner/repo.git
+        // or ssh://git@host/owner/repo.git
+        try {
+            const parsed = new URL(normalized);
+            const host = parsed.hostname;
+            const path = parsed.pathname.replace(/^\//, "");
+            normalized = `${host}/${path}`;
+        }
+        catch {
+            // Not a valid URL — return as-is after stripping .git
+        }
+    }
+    // Strip trailing .git suffix
+    normalized = normalized.replace(/\.git$/, "");
+    // Strip trailing slashes
+    normalized = normalized.replace(/\/+$/, "");
+    return normalized;
+}
+/**
+ * Get the normalized git remote URL for the current working directory.
+ * Returns null if not in a git repo or no remote is configured.
+ */
+export function getGitRemoteIdentity(cwd) {
+    try {
+        const remoteUrl = execSync("git remote get-url origin", {
+            cwd: cwd || process.cwd(),
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["pipe", "pipe", "pipe"],
+        }).trim();
+        if (!remoteUrl)
+            return null;
+        return normalizeGitRemote(remoteUrl);
+    }
+    catch {
+        // Not a git repo, no remote, or git not installed
+        return null;
+    }
+}

package/dist/mcp/server.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SseClient } from "./sse-client.js";
+import { getRoomFromConfig } from "./config-reader.js";
+import { getGitRemoteIdentity } from "./git-remote.js";
+let currentRoom = null;
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const API_URL = process.env.LETAGENTS_API_URL || "http://localhost:3001";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function apiCall(path, options) {
+    const res = await fetch(`${API_URL}${path}`, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            ...options?.headers,
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`API error ${res.status}: ${body}`);
+    }
+    return res.json();
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "letagents",
+    version: "0.2.0",
+});
+const sseClient = new SseClient(API_URL);
+// ---------------------------------------------------------------------------
+// MCP Resources
+// ---------------------------------------------------------------------------
+server.resource("project_messages", new ResourceTemplate("letagents://projects/{project_id}/messages", {
+    list: undefined,
+}), async (uri, { project_id }) => {
+    const result = await apiCall(`/projects/${encodeURIComponent(project_id)}/messages`);
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// -- create_project ---------------------------------------------------------
+server.tool("create_project", "Create a new project on Let Agents Chat. Returns a project ID and a join code that other agents can use to join.", {}, async () => {
+    const project = await apiCall("/projects", { method: "POST" });
+    // Auto-subscribe to SSE for this project
+    sseClient.subscribe(project.id, (_message) => {
+        server.server.sendResourceListChanged();
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(project, null, 2),
+            },
+        ],
+    };
+});
+// -- join_project -----------------------------------------------------------
+server.tool("join_project", "Join an existing Let Agents Chat project using a join code.", {
+    code: z.string().describe("The join code shared by the project creator (e.g. 'ABCX-7291')"),
+}, async ({ code }) => {
+    const project = await apiCall(`/projects/join/${encodeURIComponent(code)}`);
+    // Track room state
+    currentRoom = {
+        room: project.name || code,
+        project_id: project.id,
+        code: project.code || code,
+        joined_via: "join_code",
+    };
+    // Auto-subscribe to SSE for this project
+    sseClient.subscribe(project.id, (_message) => {
+        server.server.sendResourceListChanged();
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ ...project, joined_via: "join_code" }, null, 2),
+            },
+        ],
+    };
+});
+// -- join_room --------------------------------------------------------------
+server.tool("join_room", "Join a named room on Let Agents Chat. Creates the room if it doesn't exist. Use this for repo-based room joining.", {
+    name: z.string().describe("The room name to join (e.g. 'github.com/owner/repo')"),
+}, async ({ name }) => {
+    const project = await apiCall(`/projects/room/${encodeURIComponent(name)}`, { method: "POST" });
+    // Track room state
+    currentRoom = {
+        room: name,
+        project_id: project.id,
+        code: project.code,
+        joined_via: "join_room",
+    };
+    // Auto-subscribe to SSE
+    sseClient.subscribe(project.id, (_message) => {
+        server.server.sendResourceListChanged();
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ ...project, joined_via: "join_room" }, null, 2),
+            },
+        ],
+    };
+});
+// -- get_current_room -------------------------------------------------------
+server.tool("get_current_room", "Get information about the currently joined room, including how it was joined.", {}, async () => {
+    if (!currentRoom) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ connected: false, message: "Not currently in any room" }, null, 2),
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ connected: true, ...currentRoom }, null, 2),
+            },
+        ],
+    };
+});
+// -- send_message -----------------------------------------------------------
+server.tool("send_message", "Send a message to a Let Agents Chat project.", {
+    project_id: z.string().describe("The project ID to send the message to"),
+    sender: z.string().describe("Name identifying the sending agent (e.g. 'antigravity-agent')"),
+    text: z.string().describe("The message text to send"),
+}, async ({ project_id, sender, text }) => {
+    const message = await apiCall(`/projects/${encodeURIComponent(project_id)}/messages`, {
+        method: "POST",
+        body: JSON.stringify({ sender, text }),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(message, null, 2),
+            },
+        ],
+    };
+});
+// -- read_messages ----------------------------------------------------------
+server.tool("read_messages", "Read all messages from a Let Agents Chat project.", {
+    project_id: z.string().describe("The project ID to read messages from"),
+}, async ({ project_id }) => {
+    const result = await apiCall(`/projects/${encodeURIComponent(project_id)}/messages`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// -- wait_for_messages ------------------------------------------------------
+const MAX_POLL_TIMEOUT_MS = 180000; // 3 minutes
+const DEFAULT_POLL_TIMEOUT_MS = 30000; // 30 seconds
+server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat project. Blocks until new messages arrive or 30 seconds elapse. Use the after_message_id parameter to only receive messages newer than a specific message.", {
+    project_id: z.string().describe("The project ID to wait for messages in"),
+    after_message_id: z
+        .string()
+        .optional()
+        .describe("Only return messages after this message ID (e.g. 'msg_3'). If omitted, returns all existing messages immediately."),
+    timeout: z
+        .number()
+        .optional()
+        .describe("Maximum wait time in milliseconds. If set to 0, the default timeout will be used."),
+}, async ({ project_id, after_message_id, timeout }) => {
+    const serverTimeout = Math.min(Math.max(timeout || DEFAULT_POLL_TIMEOUT_MS, 1000), MAX_POLL_TIMEOUT_MS);
+    const clientTimeout = serverTimeout + 5000; // 5s buffer over server timeout
+    const params = new URLSearchParams();
+    if (after_message_id)
+        params.set("after", after_message_id);
+    params.set("timeout", String(serverTimeout));
+    const queryString = params.toString();
+    const result = await apiCall(`/projects/${encodeURIComponent(project_id)}/messages/poll?${queryString}`, { signal: AbortSignal.timeout(clientTimeout) });
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("🔌 Let Agents Chat MCP server running on stdio (v0.3.0 with repo rooms)");
+    // --- Auto-join from repo context ---
+    try {
+        // 1. Try .letagents.json config
+        const configRoom = getRoomFromConfig();
+        if (configRoom) {
+            const project = await apiCall(`/projects/room/${encodeURIComponent(configRoom)}`, { method: "POST" });
+            currentRoom = { room: configRoom, project_id: project.id, code: project.code, joined_via: "config" };
+            sseClient.subscribe(project.id, (_message) => { server.server.sendResourceListChanged(); });
+            console.error(`🏠 Auto-joined room '${configRoom}' (from .letagents.json)`);
+            return;
+        }
+        // 2. Try git remote URL
+        const gitRoom = getGitRemoteIdentity();
+        if (gitRoom) {
+            const project = await apiCall(`/projects/room/${encodeURIComponent(gitRoom)}`, { method: "POST" });
+            currentRoom = { room: gitRoom, project_id: project.id, code: project.code, joined_via: "git-remote" };
+            sseClient.subscribe(project.id, (_message) => { server.server.sendResourceListChanged(); });
+            console.error(`🏠 Auto-joined room '${gitRoom}' (inferred from git remote — consider adding a .letagents.json)`);
+            return;
+        }
+        // 3. No context found
+        console.error("ℹ️ No .letagents.json or git remote found — use join_project or join_room to connect.");
+    }
+    catch (err) {
+        // Auto-join failure should never block the MCP server
+        console.error("⚠️ Auto-join failed (server still running):", err instanceof Error ? err.message : err);
+    }
+}
+// Cleanup on exit
+process.on("SIGINT", () => {
+    sseClient.unsubscribeAll();
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    sseClient.unsubscribeAll();
+    process.exit(0);
+});
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/mcp/sse-client.js

@@ -0,0 +1,84 @@
+export class SseClient {
+    apiUrl;
+    subscriptions = new Map();
+    constructor(apiUrl) {
+        this.apiUrl = apiUrl.replace(/\/$/, "");
+    }
+    subscribe(projectId, onMessage) {
+        if (this.subscriptions.has(projectId)) {
+            return;
+        }
+        const controller = new AbortController();
+        const promise = this.consumeStream(projectId, controller.signal, onMessage)
+            .catch((error) => {
+            if (controller.signal.aborted) {
+                return;
+            }
+            console.error(`SSE subscription failed for project ${projectId}:`, error);
+        })
+            .finally(() => {
+            const current = this.subscriptions.get(projectId);
+            if (current?.controller === controller) {
+                this.subscriptions.delete(projectId);
+            }
+        });
+        this.subscriptions.set(projectId, { controller, promise });
+    }
+    unsubscribe(projectId) {
+        const subscription = this.subscriptions.get(projectId);
+        if (!subscription) {
+            return;
+        }
+        subscription.controller.abort();
+        this.subscriptions.delete(projectId);
+    }
+    unsubscribeAll() {
+        for (const projectId of this.subscriptions.keys()) {
+            this.unsubscribe(projectId);
+        }
+    }
+    async consumeStream(projectId, signal, onMessage) {
+        const response = await fetch(`${this.apiUrl}/projects/${encodeURIComponent(projectId)}/messages/stream`, {
+            headers: { Accept: "text/event-stream" },
+            signal,
+        });
+        if (!response.ok) {
+            throw new Error(`SSE request failed with status ${response.status}`);
+        }
+        if (!response.body) {
+            throw new Error("SSE response body is missing");
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (!signal.aborted) {
+            const { value, done } = await reader.read();
+            if (done) {
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            let boundaryIndex = buffer.indexOf("\n\n");
+            while (boundaryIndex !== -1) {
+                const rawEvent = buffer.slice(0, boundaryIndex);
+                buffer = buffer.slice(boundaryIndex + 2);
+                this.handleEvent(rawEvent, onMessage);
+                boundaryIndex = buffer.indexOf("\n\n");
+            }
+        }
+        const trailing = buffer + decoder.decode();
+        if (trailing.trim()) {
+            this.handleEvent(trailing, onMessage);
+        }
+    }
+    handleEvent(rawEvent, onMessage) {
+        const normalizedEvent = rawEvent.replace(/\r/g, "");
+        const dataLines = normalizedEvent
+            .split("\n")
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trimStart());
+        if (dataLines.length === 0) {
+            return;
+        }
+        onMessage(JSON.parse(dataLines.join("\n")));
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "letagents",
+  "version": "0.3.0",
+  "description": "Let Agents Chat — MCP server for AI agent communication",
+  "type": "module",
+  "main": "dist/mcp/server.js",
+  "bin": {
+    "letagents": "dist/mcp/server.js"
+  },
+  "files": [
+    "dist/mcp/**",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev:api": "tsx src/api/server.ts",
+    "dev:mcp": "tsx src/mcp/server.ts"
+  },
+  "keywords": [
+    "mcp",
+    "ai-agents",
+    "multi-agent",
+    "chat",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EmmyMay/letagents.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "better-sqlite3": "^12.8.0",
+    "express": "^5.1.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/express": "^5.0.2",
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}