mcp-agent-broker 1.0.0 → 1.0.1

package/README.md

@@ -1,31 +1,77 @@
 # MCP Agent Broker
 
-The Model Context Protocol (MCP) Agent Broker is a centralized service designed to orchestrate and manage autonomous coding agents.
+The Model Context Protocol (MCP) Agent Broker is a centralized service designed to orchestrate and manage autonomous coding agents. 
+
+It acts as a middleware that securely maps AI Agents (Principals) to tasks, enforcing distributed locks (Fencing Tokens) so multiple agents don't step on each other's toes when working on the same repository.
 
 ## Features
 * **MCP Server Integration:** Natively implements the MCP SDK via Server-Sent Events (SSE).
+* **Secure Authentication:** Validates API keys against securely hashed database records.
 * **Distributed Locking:** Safely hand off tasks between implementer agents and reviewer agents using fencing tokens.
 * **Transactional Outbox:** Guaranteed delivery of domain events without dual-write issues.
 * **Event Relay:** Real-time event broadcasting over Redis Pub/Sub.
 
-## Prerequisites
-You will need Docker installed to run the dependencies:
-* PostgreSQL
-* Redis
-* MinIO
+---
+
+## Getting Started
 
-## Usage
+### 1. Start the Infrastructure
+The broker requires PostgreSQL and Redis. We provide a `docker-compose.yml` to spin up everything (including the broker itself) instantly.
 
-1. Start the infrastructure:
 ```bash
 docker compose up -d
 ```
+*Note: If you are doing local development, you can run `docker compose up -d postgres redis` and then run the app locally using `npm run dev`.*
+
+### 2. Generate an API Key
+To connect to the broker, your Agent must have an API Key. We provide a seed script to generate your first Workspace, Principal, and API Key.
 
-2. Run the server:
 ```bash
-npm start
+npx tsx seed_api_key.ts
 ```
-The server will bind to `http://localhost:3000/mcp/sse`.
+*Take note of the API Key (e.g. `test-api-key-123`) output by the terminal.*
+
+### 3. Connect your Agents
+Point your MCP-compatible client to the broker's endpoint and pass your API key as a Bearer token.
+
+**Programmatic Example (TypeScript):**
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+
+const transport = new SSEClientTransport(new URL("http://localhost:3000/mcp/sse"), {
+  eventSourceInit: {
+    headers: { Authorization: "Bearer test-api-key-123" }
+  } as any,
+  requestInit: {
+    headers: { Authorization: "Bearer test-api-key-123" }
+  }
+});
+
+const client = new Client({ name: "my-agent", version: "1.0.0" }, { capabilities: {} });
+await client.connect(transport);
+
+// Register your agent!
+await client.request({
+  method: "tools/call",
+  params: {
+    name: "register_agent",
+    arguments: { 
+      workspaceId: "00000000-0000-0000-0000-000000000000", 
+      name: "My Implementer Agent", 
+      version: "1.0", 
+      capabilities: ["execute"] 
+    }
+  }
+}, CallToolResultSchema);
+```
+
+### 4. Listen to Real-Time Events
+Any downstream CI dashboard or review agent can connect to the Redis server and subscribe to `workspace:{workspace_id}:events` to see real-time updates as tasks are created and leases are acquired!
+
+---
 
-3. Connect your Agents:
-Point your MCP-compatible client (like Claude Code) to `http://localhost:3000/mcp/sse`. They can now invoke tools like `register_agent`, `create_task`, and `acquire_task_lease`!
+## Future Improvements for Contributors
+* Implement standard OAuth2 / OIDC for user-facing dashboards.
+* Extend the `Review Module` to enforce reviewer sign-offs before pushing to main branches.
+* Implement the Fencing Token check in a Git Hook or CI/CD layer.

package/dist/infrastructure/db/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.idempotencyRecords = exports.outbox = exports.events = exports.leases = exports.taskAttempts = exports.tasks = exports.agentInstances = exports.agentDefinitions = exports.workspaces = exports.leaseTypeEnum = exports.leaseStatusEnum = exports.agentStatusEnum = exports.workspaceStatusEnum = exports.taskStateEnum = void 0;
+exports.idempotencyRecords = exports.outbox = exports.events = exports.leases = exports.taskAttempts = exports.tasks = exports.agentInstances = exports.agentDefinitions = exports.apiKeys = exports.principals = exports.workspaces = exports.leaseTypeEnum = exports.leaseStatusEnum = exports.agentStatusEnum = exports.workspaceStatusEnum = exports.taskStateEnum = void 0;
 const pg_core_1 = require("drizzle-orm/pg-core");
 exports.taskStateEnum = (0, pg_core_1.pgEnum)('task_state', [
     'draft', 'ready', 'leased', 'running', 'blocked',
@@ -19,6 +19,16 @@ exports.workspaces = (0, pg_core_1.pgTable)('workspaces', {
     createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
     updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
 });
+exports.principals = (0, pg_core_1.pgTable)('principals', {
+    id: (0, pg_core_1.uuid)('id').primaryKey(),
+    name: (0, pg_core_1.text)('name').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+exports.apiKeys = (0, pg_core_1.pgTable)('api_keys', {
+    keyHash: (0, pg_core_1.text)('key_hash').primaryKey(),
+    principalId: (0, pg_core_1.uuid)('principal_id').notNull().references(() => exports.principals.id),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
 exports.agentDefinitions = (0, pg_core_1.pgTable)('agent_definitions', {
     id: (0, pg_core_1.uuid)('id').primaryKey(),
     name: (0, pg_core_1.text)('name').notNull(),

package/dist/modules/identity/agent.service.js

@@ -17,7 +17,7 @@ class AgentService {
         return workspace;
     }
     async registerAgent(params) {
-        const workspace = await this.ensureDefaultWorkspace();
+        const workspace = await this.ensureDefaultWorkspace(); // Fallback logic or just rely on params
         // 1. Create or find agent definition
         let [definition] = await index_js_1.db.select().from(schema_js_1.agentDefinitions)
             .where((0, drizzle_orm_1.eq)(schema_js_1.agentDefinitions.name, params.name))
@@ -44,8 +44,8 @@ class AgentService {
         const [instance] = await index_js_1.db.insert(schema_js_1.agentInstances).values({
             id: (0, crypto_1.randomUUID)(),
             agentDefinitionId: definition.id,
-            workspaceId: workspace.id,
-            principalId: (0, crypto_1.randomUUID)(), // Mocking principal ID for Phase 0
+            workspaceId: params.workspaceId,
+            principalId: params.principalId,
             capabilitiesJson: params.capabilities,
             status: "connected",
         }).returning();

package/dist/transport/mcp/index.js

@@ -4,6 +4,10 @@ exports.setupMcpTransport = setupMcpTransport;
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const crypto_1 = require("crypto");
+const drizzle_orm_1 = require("drizzle-orm");
+const index_js_2 = require("../../infrastructure/db/index.js");
+const schema_js_1 = require("../../infrastructure/db/schema.js");
 const agent_service_js_1 = require("../../modules/identity/agent.service.js");
 const task_service_js_1 = require("../../modules/task/task.service.js");
 const lease_service_js_1 = require("../../modules/lease/lease.service.js");
@@ -11,6 +15,19 @@ async function setupMcpTransport(fastify) {
     // Store transports for the POST /mcp/message route
     const transports = new Map();
     fastify.get("/mcp/sse", async (request, reply) => {
+        const authHeader = request.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            reply.status(401).send({ error: "Missing or invalid Authorization header" });
+            return;
+        }
+        const token = authHeader.split(' ')[1];
+        const keyHash = (0, crypto_1.createHash)('sha256').update(token).digest('hex');
+        const [apiKeyRecord] = await index_js_2.db.select().from(schema_js_1.apiKeys).where((0, drizzle_orm_1.eq)(schema_js_1.apiKeys.keyHash, keyHash));
+        if (!apiKeyRecord) {
+            reply.status(401).send({ error: "Invalid API Key" });
+            return;
+        }
+        const principalId = apiKeyRecord.principalId;
         // Hijack the Fastify response so we can stream SSE headers manually
         reply.hijack();
         const transport = new sse_js_1.SSEServerTransport("/mcp/message", reply.raw);
@@ -75,7 +92,9 @@ async function setupMcpTransport(fastify) {
             if (req.params.name === "register_agent") {
                 try {
                     const args = req.params.arguments;
-                    const instance = await agent_service_js_1.agentService.registerAgent({
+                    const agentInstance = await agent_service_js_1.agentService.registerAgent({
+                        workspaceId: args.workspaceId || (0, crypto_1.randomUUID)(), // Temporary fallback
+                        principalId: principalId,
                         name: args.name,
                         version: args.version,
                         capabilities: args.capabilities,
@@ -84,7 +103,7 @@ async function setupMcpTransport(fastify) {
                         content: [
                             {
                                 type: "text",
-                                text: `Agent registered successfully! Instance ID: ${instance.id}`
+                                text: `Agent registered successfully! Instance ID: ${agentInstance.id}`
                             }
                         ]
                     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-agent-broker",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "main": "dist/app.js",
   "bin": {
     "mcp-agent-broker": "dist/app.js"
@@ -9,7 +9,7 @@
     "build": "tsc",
     "start": "node dist/app.js",
     "dev": "tsx watch src/app.ts",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest run"
   },
   "keywords": [],
   "author": "",
@@ -30,6 +30,7 @@
     "@types/pg": "^8.20.0",
     "drizzle-kit": "^0.31.10",
     "tsx": "^4.23.1",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   }
 }

package/seed_api_key.ts

@@ -0,0 +1,30 @@
+import { db } from './src/infrastructure/db/index.js';
+import { principals, apiKeys, workspaces } from './src/infrastructure/db/schema.js';
+import { randomUUID, createHash } from 'crypto';
+
+async function seed() {
+  const principalId = randomUUID();
+  const rawKey = 'test-api-key-123';
+  const keyHash = createHash('sha256').update(rawKey).digest('hex');
+
+  const workspaceId = '00000000-0000-0000-0000-000000000000';
+  await db.insert(workspaces).values({
+    id: workspaceId,
+    name: 'Test Workspace',
+  }).onConflictDoNothing();
+
+  await db.insert(principals).values({
+    id: principalId,
+    name: 'Test Service Account',
+  }).onConflictDoNothing();
+
+  await db.insert(apiKeys).values({
+    keyHash,
+    principalId,
+  });
+
+  console.log('Seeded principal:', principalId);
+  console.log('API Key:', rawKey);
+  process.exit(0);
+}
+seed().catch(console.error);

package/docker-compose.yml

@@ -1,41 +0,0 @@
-services:
-  postgres:
-    image: postgres:16-alpine
-    container_name: mab-postgres
-    environment:
-      POSTGRES_USER: mab_user
-      POSTGRES_PASSWORD: mab_password
-      POSTGRES_DB: mab_db
-    ports:
-      - "5433:5432"
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    restart: unless-stopped
-
-  redis:
-    image: redis:7-alpine
-    container_name: mab-redis
-    ports:
-      - "6379:6379"
-    volumes:
-      - redis_data:/data
-    restart: unless-stopped
-
-  minio:
-    image: minio/minio:latest
-    container_name: mab-minio
-    environment:
-      MINIO_ROOT_USER: mab_admin
-      MINIO_ROOT_PASSWORD: mab_password123
-    command: server /data --console-address ":9001"
-    ports:
-      - "9000:9000"
-      - "9001:9001"
-    volumes:
-      - minio_data:/data
-    restart: unless-stopped
-
-volumes:
-  postgres_data:
-  redis_data:
-  minio_data:

package/drizzle.config.ts

@@ -1,10 +0,0 @@
-import { defineConfig } from "drizzle-kit";
-
-export default defineConfig({
-  schema: "./src/infrastructure/db/schema.ts",
-  out: "./src/infrastructure/db/migrations",
-  dialect: "postgresql",
-  dbCredentials: {
-    url: process.env.DATABASE_URL || "postgres://mab_user:mab_password@127.0.0.1:5433/mab_db"
-  }
-});

package/src/app.ts

@@ -1,31 +0,0 @@
-#!/usr/bin/env node
-import Fastify from 'fastify';
-import { setupMcpTransport } from './transport/mcp/index.js';
-import { db } from './infrastructure/db/index.js';
-import { outboxRelay } from './workers/outbox-relay.js';
-
-const fastify = Fastify({
-  logger: true
-});
-
-fastify.get('/health', async (request, reply) => {
-  return { status: 'ok', service: 'mcp-agent-broker' };
-});
-
-// Start the server
-const start = async () => {
-  try {
-    await setupMcpTransport(fastify);
-    
-    // Start background workers
-    outboxRelay.start();
-    
-    await fastify.listen({ port: 3000, host: '0.0.0.0' });
-    fastify.log.info(`Server listening on ${fastify.server.address()}`);
-  } catch (err) {
-    fastify.log.error(err);
-    process.exit(1);
-  }
-};
-
-start();

package/src/infrastructure/db/index.ts

@@ -1,10 +0,0 @@
-import { drizzle } from 'drizzle-orm/node-postgres';
-import { Pool } from 'pg';
-import * as schema from './schema';
-
-// Use a connection pool for the Fastify app
-const pool = new Pool({
-  connectionString: process.env.DATABASE_URL || "postgres://mab_user:mab_password@127.0.0.1:5433/mab_db"
-});
-
-export const db = drizzle(pool, { schema });

package/src/infrastructure/db/migrations/0000_flawless_vanisher.sql

@@ -1,103 +0,0 @@
-CREATE TYPE "public"."lease_status" AS ENUM('active', 'released', 'expired', 'revoked');--> statement-breakpoint
-CREATE TYPE "public"."lease_type" AS ENUM('execution', 'review');--> statement-breakpoint
-CREATE TYPE "public"."task_state" AS ENUM('draft', 'ready', 'leased', 'running', 'blocked', 'awaiting_review', 'changes_requested', 'completed', 'failed', 'canceled', 'superseded');--> statement-breakpoint
-CREATE TABLE "events" (
-	"event_seq" bigserial PRIMARY KEY NOT NULL,
-	"event_id" uuid NOT NULL,
-	"event_type" text NOT NULL,
-	"event_version" integer NOT NULL,
-	"workspace_id" uuid NOT NULL,
-	"aggregate_type" text NOT NULL,
-	"aggregate_id" uuid NOT NULL,
-	"aggregate_version" bigint NOT NULL,
-	"actor_type" text NOT NULL,
-	"actor_id" uuid,
-	"correlation_id" uuid NOT NULL,
-	"causation_id" uuid,
-	"payload" jsonb NOT NULL,
-	"occurred_at" timestamp with time zone DEFAULT now() NOT NULL,
-	CONSTRAINT "events_event_id_unique" UNIQUE("event_id"),
-	CONSTRAINT "events_aggregate_type_aggregate_id_aggregate_version_unique" UNIQUE("aggregate_type","aggregate_id","aggregate_version")
-);
---> statement-breakpoint
-CREATE TABLE "idempotency_records" (
-	"principal_id" uuid NOT NULL,
-	"operation" text NOT NULL,
-	"idempotency_key" text NOT NULL,
-	"request_hash" text NOT NULL,
-	"response_json" jsonb,
-	"response_status" text NOT NULL,
-	"resource_id" uuid,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"expires_at" timestamp with time zone NOT NULL,
-	CONSTRAINT "idempotency_records_principal_id_operation_idempotency_key_pk" PRIMARY KEY("principal_id","operation","idempotency_key")
-);
---> statement-breakpoint
-CREATE TABLE "leases" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"workspace_id" uuid NOT NULL,
-	"task_id" uuid NOT NULL,
-	"task_attempt_id" uuid,
-	"agent_instance_id" uuid NOT NULL,
-	"lease_type" "lease_type" NOT NULL,
-	"status" "lease_status" NOT NULL,
-	"fencing_token" bigint NOT NULL,
-	"acquired_at" timestamp with time zone NOT NULL,
-	"renewed_at" timestamp with time zone NOT NULL,
-	"expires_at" timestamp with time zone NOT NULL,
-	"released_at" timestamp with time zone,
-	CONSTRAINT "leases_task_id_lease_type_fencing_token_unique" UNIQUE("task_id","lease_type","fencing_token")
-);
---> statement-breakpoint
-CREATE TABLE "outbox" (
-	"event_id" uuid PRIMARY KEY NOT NULL,
-	"available_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"attempts" integer DEFAULT 0 NOT NULL,
-	"locked_by" text,
-	"locked_until" timestamp with time zone,
-	"published_at" timestamp with time zone,
-	"last_error" text,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL
-);
---> statement-breakpoint
-CREATE TABLE "task_attempts" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"workspace_id" uuid NOT NULL,
-	"task_id" uuid NOT NULL,
-	"attempt_number" integer NOT NULL,
-	"agent_instance_id" uuid NOT NULL,
-	"status" text NOT NULL,
-	"started_at" timestamp with time zone,
-	"ended_at" timestamp with time zone,
-	"outcome" text,
-	CONSTRAINT "task_attempts_task_id_attempt_number_unique" UNIQUE("task_id","attempt_number")
-);
---> statement-breakpoint
-CREATE TABLE "tasks" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"workspace_id" uuid NOT NULL,
-	"repository_id" uuid NOT NULL,
-	"session_id" uuid,
-	"objective" text NOT NULL,
-	"description" text DEFAULT '' NOT NULL,
-	"acceptance_criteria" jsonb DEFAULT '[]' NOT NULL,
-	"constraints" jsonb DEFAULT '[]' NOT NULL,
-	"priority" smallint DEFAULT 3 NOT NULL,
-	"state" "task_state" DEFAULT 'draft' NOT NULL,
-	"base_commit_sha" text,
-	"active_execution_lease_id" uuid,
-	"active_review_lease_id" uuid,
-	"next_fencing_token" bigint DEFAULT 0 NOT NULL,
-	"version" bigint DEFAULT 1 NOT NULL,
-	"created_by" uuid NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"completed_at" timestamp with time zone
-);
---> statement-breakpoint
-ALTER TABLE "leases" ADD CONSTRAINT "leases_task_id_tasks_id_fk" FOREIGN KEY ("task_id") REFERENCES "public"."tasks"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "leases" ADD CONSTRAINT "leases_task_attempt_id_task_attempts_id_fk" FOREIGN KEY ("task_attempt_id") REFERENCES "public"."task_attempts"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "outbox" ADD CONSTRAINT "outbox_event_id_events_event_id_fk" FOREIGN KEY ("event_id") REFERENCES "public"."events"("event_id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "task_attempts" ADD CONSTRAINT "task_attempts_task_id_tasks_id_fk" FOREIGN KEY ("task_id") REFERENCES "public"."tasks"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-CREATE INDEX "events_workspace_cursor" ON "events" USING btree ("workspace_id","event_seq");--> statement-breakpoint
-CREATE INDEX "idempotency_expiry" ON "idempotency_records" USING btree ("expires_at");

package/src/infrastructure/db/migrations/0001_fearless_sersi.sql

@@ -1,36 +0,0 @@
-CREATE TYPE "public"."agent_status" AS ENUM('connected', 'degraded', 'disconnected', 'revoked');--> statement-breakpoint
-CREATE TYPE "public"."workspace_status" AS ENUM('active', 'archived');--> statement-breakpoint
-CREATE TABLE "agent_definitions" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"name" text NOT NULL,
-	"vendor" text,
-	"version" text NOT NULL,
-	"integration_type" text,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
---> statement-breakpoint
-CREATE TABLE "agent_instances" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"agent_definition_id" uuid NOT NULL,
-	"workspace_id" uuid NOT NULL,
-	"principal_id" uuid NOT NULL,
-	"status" "agent_status" DEFAULT 'connected' NOT NULL,
-	"capabilities_json" jsonb DEFAULT '[]' NOT NULL,
-	"last_heartbeat_at" timestamp with time zone,
-	"revoked_at" timestamp with time zone,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
---> statement-breakpoint
-CREATE TABLE "workspaces" (
-	"id" uuid PRIMARY KEY NOT NULL,
-	"organization_id" uuid,
-	"name" text NOT NULL,
-	"status" "workspace_status" DEFAULT 'active' NOT NULL,
-	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
-	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
-);
---> statement-breakpoint
-ALTER TABLE "agent_instances" ADD CONSTRAINT "agent_instances_agent_definition_id_agent_definitions_id_fk" FOREIGN KEY ("agent_definition_id") REFERENCES "public"."agent_definitions"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "agent_instances" ADD CONSTRAINT "agent_instances_workspace_id_workspaces_id_fk" FOREIGN KEY ("workspace_id") REFERENCES "public"."workspaces"("id") ON DELETE no action ON UPDATE no action;