@synth-deploy/server 0.1.0

package/src/mcp/resources.ts

@@ -0,0 +1,98 @@
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DebriefReader } from "@synth-deploy/core";
+import type { DeploymentStore } from "../agent/synth-agent.js";
+
+/**
+ * Register MCP resources. These expose Synth state to MCP clients
+ * as readable data — Debrief entries, deployment records, etc.
+ */
+export function registerResources(
+  mcp: McpServer,
+  debrief: DebriefReader,
+  deployments: DeploymentStore,
+): void {
+  // Recent debrief entries — scoped to a specific partition
+  mcp.registerResource(
+    "recent-debrief-entries",
+    new ResourceTemplate("debrief://partition/{partitionId}/recent", {
+      list: undefined,
+    }),
+    {
+      title: "Recent Debrief Entries (Partition-Scoped)",
+      description:
+        "The most recent Debrief entries for a specific partition. " +
+        "Each entry records what the agent decided and why, in plain language.",
+      mimeType: "application/json",
+    },
+    async (uri, { partitionId }) => ({
+      contents: [
+        {
+          uri: uri.href,
+          text: JSON.stringify(debrief.getByPartition(partitionId as string).slice(-20), null, 2),
+        },
+      ],
+    }),
+  );
+
+  // Debrief entries for a specific deployment
+  mcp.registerResource(
+    "deployment-debrief",
+    new ResourceTemplate("debrief://deployment/{deploymentId}", {
+      list: undefined,
+    }),
+    {
+      title: "Deployment Debrief",
+      description:
+        "All Debrief entries for a specific deployment, showing the full reasoning chain.",
+      mimeType: "application/json",
+    },
+    async (uri, { deploymentId }) => {
+      const deployment = deployments.get(deploymentId as string);
+      if (!deployment) {
+        return { contents: [{ uri: uri.href, text: JSON.stringify({ error: "Deployment not found" }) }] };
+      }
+      const entries = debrief.getByDeployment(deploymentId as string);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: JSON.stringify(entries, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  // Deployment record
+  mcp.registerResource(
+    "deployment",
+    new ResourceTemplate("deployment://{deploymentId}", {
+      list: async () => ({
+        resources: deployments.list().map((d) => ({
+          uri: `deployment://${d.id}`,
+          name: `${d.artifactId} v${d.version} → ${d.environmentId}`,
+        })),
+      }),
+    }),
+    {
+      title: "Deployment Record",
+      description: "Full deployment record including status, variables, and debrief entry references.",
+      mimeType: "application/json",
+    },
+    async (uri, { deploymentId }) => {
+      const deployment = deployments.get(deploymentId as string);
+      if (!deployment) {
+        return { contents: [{ uri: uri.href, text: "Not found" }] };
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: JSON.stringify(deployment, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/src/mcp/server.ts

@@ -0,0 +1,34 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DebriefWriter, DebriefReader, IPartitionStore, IEnvironmentStore, IArtifactStore } from "@synth-deploy/core";
+import type { SynthAgent, DeploymentStore } from "../agent/synth-agent.js";
+import { registerTools } from "./tools.js";
+import { registerResources } from "./resources.js";
+
+/**
+ * Create and configure the MCP server with all Synth tools and resources.
+ */
+export function createMcpServer(deps: {
+  agent: SynthAgent;
+  debrief: DebriefWriter & DebriefReader;
+  partitions: IPartitionStore;
+  environments: IEnvironmentStore;
+  deployments: DeploymentStore;
+  artifactStore: IArtifactStore;
+}): McpServer {
+  const mcp = new McpServer(
+    {
+      name: "synth",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        logging: {},
+      },
+    },
+  );
+
+  registerTools(mcp, deps.agent, deps.partitions, deps.environments, deps.deployments, deps.artifactStore);
+  registerResources(mcp, deps.debrief, deps.deployments);
+
+  return mcp;
+}

package/src/mcp/tools.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SynthAgent, DeploymentStore } from "../agent/synth-agent.js";
+import type { IArtifactStore, IEnvironmentStore, IPartitionStore } from "@synth-deploy/core";
+
+/**
+ * Register MCP tools on the server. These are the actions MCP clients
+ * (Claude, agents, CLI tools) can invoke.
+ */
+export function registerTools(
+  mcp: McpServer,
+  agent: SynthAgent,
+  partitions: IPartitionStore,
+  environments: IEnvironmentStore,
+  deployments: DeploymentStore,
+  artifactStore: IArtifactStore,
+): void {
+  mcp.registerTool(
+    "trigger-deployment",
+    {
+      title: "Trigger Deployment",
+      description:
+        "Trigger a deployment of an artifact to an environment. " +
+        "The server agent will resolve variables, make decisions, and record everything to the Debrief.",
+      inputSchema: {
+        artifactId: z.string().describe("The artifact to deploy"),
+        environmentId: z.string().describe("Target environment ID"),
+        partitionId: z.string().optional().describe("Target partition ID (optional)"),
+        version: z.string().describe("Version to deploy"),
+        variables: z.record(z.string()).optional().describe("Override variables for this deployment"),
+      },
+    },
+    async ({ artifactId, environmentId, partitionId, version, variables }) => {
+      const artifact = artifactStore.get(artifactId);
+      if (!artifact) {
+        return {
+          content: [{ type: "text", text: `Error: Artifact not found: ${artifactId}` }],
+          isError: true,
+        };
+      }
+
+      const environment = environments.get(environmentId);
+      if (!environment) {
+        return {
+          content: [{ type: "text", text: `Error: Environment not found: ${environmentId}` }],
+          isError: true,
+        };
+      }
+
+      if (partitionId) {
+        const partition = partitions.get(partitionId);
+        if (!partition) {
+          return {
+            content: [{ type: "text", text: `Error: Partition not found: ${partitionId}` }],
+            isError: true,
+          };
+        }
+      }
+
+      const deployment = await agent.triggerDeployment({
+        artifactId,
+        artifactVersionId: version,
+        environmentId,
+        partitionId,
+        triggeredBy: "agent",
+        variables,
+      });
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                deploymentId: deployment.id,
+                status: deployment.status,
+                version: deployment.version,
+                debriefEntries: deployment.debriefEntryIds.length,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    },
+  );
+
+  mcp.registerTool(
+    "get-deployment-status",
+    {
+      title: "Get Deployment Status",
+      description: "Get the current status and Debrief entries for a deployment.",
+      inputSchema: {
+        deploymentId: z.string().describe("The deployment ID to check"),
+      },
+    },
+    async ({ deploymentId }) => {
+      const deployment = deployments.get(deploymentId);
+      if (!deployment) {
+        return {
+          content: [{ type: "text", text: `Error: Deployment not found: ${deploymentId}` }],
+          isError: true,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(deployment, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/src/middleware/auth.ts

@@ -0,0 +1,103 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
+import { SignJWT, jwtVerify } from "jose";
+import type { IUserStore, IUserRoleStore, ISessionStore, UserId, Permission } from "@synth-deploy/core";
+
+export interface AuthenticatedUser {
+  id: UserId;
+  email: string;
+  name: string;
+  permissions: Permission[];
+}
+
+declare module "fastify" {
+  interface FastifyRequest {
+    user?: AuthenticatedUser;
+  }
+}
+
+const EXEMPT_ROUTES = ["/health", "/api/health", "/api/auth/login", "/api/auth/register", "/api/auth/refresh", "/api/auth/status", "/api/auth/providers", "/api/envoy/report"];
+const EXEMPT_PREFIXES = ["/api/auth/oidc/", "/api/auth/callback/oidc/", "/api/auth/saml/", "/api/auth/callback/saml/", "/api/auth/ldap/", "/api/intake/webhook/"];
+// Envoy callback endpoints — validated by envoy token, not user JWT
+const EXEMPT_PATTERNS = [/^\/api\/deployments\/[^/]+\/progress$/];
+
+/**
+ * Registers JWT-based authentication middleware on a Fastify instance.
+ *
+ * All /api/ and /mcp routes require a valid JWT Bearer token,
+ * except routes listed in EXEMPT_ROUTES. Static file serving and
+ * health endpoints are always accessible.
+ */
+export function registerAuthMiddleware(
+  app: FastifyInstance,
+  userStore: IUserStore,
+  userRoleStore: IUserRoleStore,
+  sessionStore: ISessionStore,
+  jwtSecret: Uint8Array,
+): { enabled: boolean } {
+  app.addHook("onRequest", async (request: FastifyRequest, reply: FastifyReply) => {
+    // Skip exempt routes
+    if (EXEMPT_ROUTES.some((r) => request.url.startsWith(r))) return;
+    // Skip OIDC auth routes (dynamic paths)
+    if (EXEMPT_PREFIXES.some((p) => request.url.startsWith(p))) return;
+    // Skip envoy callback endpoints (validated by envoy token in the route handler)
+    if (EXEMPT_PATTERNS.some((p) => p.test(request.url))) return;
+    // Also skip static file serving (non-API routes), but NOT /mcp — it requires auth
+    if (!request.url.startsWith("/api/") && !request.url.startsWith("/mcp")) return;
+
+    // Accept token from Authorization header or ?token= query param
+    // (EventSource API cannot send headers, so SSE endpoints use query param)
+    const authHeader = request.headers.authorization;
+    const queryToken = (request.query as Record<string, string>)?.token;
+    const rawToken = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : queryToken;
+    if (!rawToken) {
+      reply.status(401).send({ error: "Authentication required" });
+      return;
+    }
+
+    const token = rawToken;
+    try {
+      const { payload } = await jwtVerify(token, jwtSecret);
+      const userId = payload.sub as UserId;
+      const user = userStore.getById(userId);
+      if (!user) {
+        reply.status(401).send({ error: "User not found" });
+        return;
+      }
+      const session = sessionStore.getByToken(token);
+      if (!session) {
+        reply.status(401).send({ error: "Session expired" });
+        return;
+      }
+      const permissions = userRoleStore.getUserPermissions(userId);
+      request.user = { id: userId, email: user.email, name: user.name, permissions };
+    } catch {
+      reply.status(401).send({ error: "Invalid token" });
+    }
+  });
+
+  return { enabled: true };
+}
+
+export async function generateTokens(
+  userId: UserId,
+  jwtSecret: Uint8Array,
+): Promise<{ token: string; refreshToken: string; expiresAt: Date }> {
+  const sessionTtl = process.env.SYNTH_SESSION_TTL ?? "8h";
+  const sessionTtlMs = sessionTtl.endsWith("h")
+    ? parseInt(sessionTtl) * 60 * 60 * 1000
+    : sessionTtl.endsWith("m")
+    ? parseInt(sessionTtl) * 60 * 1000
+    : 8 * 60 * 60 * 1000;
+
+  const token = await new SignJWT({ sub: userId })
+    .setProtectedHeader({ alg: "HS256" })
+    .setExpirationTime(sessionTtl)
+    .sign(jwtSecret);
+
+  const refreshToken = await new SignJWT({ sub: userId, type: "refresh" })
+    .setProtectedHeader({ alg: "HS256" })
+    .setExpirationTime("7d")
+    .sign(jwtSecret);
+
+  return { token, refreshToken, expiresAt: new Date(Date.now() + sessionTtlMs) };
+}

package/src/middleware/permissions.ts

@@ -0,0 +1,35 @@
+import type { FastifyRequest, FastifyReply } from "fastify";
+import type { Permission, EnterpriseFeature } from "@synth-deploy/core";
+import { requireEnterprise, ENTERPRISE_FEATURES } from "@synth-deploy/core";
+
+/**
+ * Returns a Fastify preHandler that checks whether the authenticated user
+ * has all of the specified permissions.
+ */
+export function requirePermission(...permissions: Permission[]) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const user = request.user;
+    if (!user) {
+      reply.status(401).send({ error: "Authentication required" });
+      return;
+    }
+    const missing = permissions.filter((p) => !user.permissions.includes(p));
+    if (missing.length > 0) {
+      reply.status(403).send({
+        error: "Forbidden",
+        required: permissions,
+        message: `This action requires: ${missing.join(", ")}`,
+      });
+    }
+  };
+}
+
+/**
+ * Returns a Fastify preHandler that gates an enterprise-only feature.
+ * Throws EditionError (caught by global error handler → 402) on Community edition.
+ */
+export function requireEdition(feature: EnterpriseFeature) {
+  return async (_request: FastifyRequest, _reply: FastifyReply) => {
+    requireEnterprise(feature);
+  };
+}