@interf/gateway 0.0.1

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("interf-gateway running on stdio");

package/dist/server.js

@@ -0,0 +1,401 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import YAML from "yaml";
+import Anthropic from "@anthropic-ai/sdk";
+const SERVER_INSTRUCTIONS = `You are connected to the Interf Gateway — the Agent Readiness Protocol.
+
+Interf helps coding agents understand what it takes for their AI-powered tool to be adopted
+by real enterprises. When a coding agent builds something (a CRM automation, an internal tool,
+a data pipeline), Interf answers: "What does an enterprise need before they can actually deploy this?"
+
+## What you can do with Interf
+
+1. **Generate an interf.yaml manifest** — Use get_protocol_guidance to learn the spec, then
+   help the user create an interf.yaml that describes their agent/tool's enterprise dependencies.
+
+2. **Run a simulation** — Pass a manifest + enterprise profiles to run_simulation to see
+   estimated integration timelines, stakeholder requirements, and risk factors.
+
+## Workflow
+1. Call get_protocol_guidance to understand the protocol
+2. Help the user define their agent's manifest (interf.yaml)
+3. Run simulations against target enterprise profiles
+`;
+const PROTOCOL_GUIDANCE = `# Interf Protocol — Agent Readiness Specification
+
+## Overview
+An \`interf.yaml\` manifest declares everything an AI agent/tool needs from an enterprise
+environment to function. It's the bridge between "works on my laptop" and "deployed in prod."
+
+## interf.yaml Schema
+
+\`\`\`yaml
+name: string           # Agent/tool name
+version: string        # Semver
+description: string    # What it does
+
+dependencies:
+  - type: string       # One of: api, database, auth, storage, network, secret, approval, compliance
+    name: string       # Human-readable name
+    description: string # What this dependency is for
+    required: boolean  # Is this blocking?
+    config:            # Type-specific configuration
+      # For api: endpoint, method, auth_type, scopes
+      # For database: engine, access_level (read/write/admin)
+      # For auth: provider, protocol (oauth2/saml/api_key), scopes
+      # For storage: type (s3/gcs/local), access_level
+      # For network: hosts, ports, protocol
+      # For secret: names (list of env vars or vault paths)
+      # For approval: approver_role, justification
+      # For compliance: frameworks (SOC2/HIPAA/GDPR), controls
+
+capabilities:
+  - string             # What the agent can do (e.g. "read_contacts", "send_email")
+
+risk_level: low | medium | high | critical
+\`\`\`
+
+## Example interf.yaml
+
+\`\`\`yaml
+name: crm-automation-agent
+version: 0.1.0
+description: Automates CRM data entry and follow-up scheduling
+
+dependencies:
+  - type: api
+    name: Salesforce API
+    description: Read/write contacts and opportunities
+    required: true
+    config:
+      endpoint: https://api.salesforce.com
+      auth_type: oauth2
+      scopes: [api, refresh_token]
+
+  - type: auth
+    name: SSO Integration
+    description: Enterprise SSO for agent authentication
+    required: true
+    config:
+      provider: okta
+      protocol: saml
+
+  - type: secret
+    name: API Credentials
+    description: Salesforce client credentials
+    required: true
+    config:
+      names: [SF_CLIENT_ID, SF_CLIENT_SECRET, SF_REFRESH_TOKEN]
+
+  - type: compliance
+    name: SOC2 Compliance
+    description: Required for handling customer PII
+    required: true
+    config:
+      frameworks: [SOC2]
+      controls: [data_encryption, audit_logging, access_review]
+
+  - type: approval
+    name: Security Review
+    description: InfoSec team must approve API access
+    required: true
+    config:
+      approver_role: security_engineer
+      justification: Agent accesses customer PII via Salesforce
+
+capabilities:
+  - read_contacts
+  - write_contacts
+  - read_opportunities
+  - schedule_followups
+
+risk_level: high
+\`\`\`
+
+## Instructions for Coding Agents
+
+When helping a user create an interf.yaml:
+1. Ask what the agent/tool does
+2. Identify all external systems it needs to talk to (APIs, databases, etc.)
+3. Identify auth requirements
+4. Identify secrets/credentials needed
+5. Identify compliance requirements based on data sensitivity
+6. Identify stakeholder approvals needed
+7. Assess overall risk level
+8. Generate the YAML manifest
+
+Then offer to run a simulation against target enterprise profiles.
+`;
+const SIMULATION_PROMPT = `You are an enterprise integration analyst. Given an agent's interf.yaml manifest and a target enterprise profile, produce a realistic deployment simulation.
+
+For each dependency in the manifest, analyze:
+- estimated_days: realistic business days to integrate (not just engineering — include procurement, legal, security review)
+- stakeholders: specific roles that must be involved
+- risks: concrete risks for this specific dependency at this specific enterprise type
+- recommendation: actionable next step
+
+Consider the enterprise profile carefully:
+- Fortune 500 / large enterprise: heavy governance, CAB reviews, vendor risk assessment, 3-6 month cycles
+- Regulated (bank, healthcare): add regulatory review, compliance mapping, audit requirements
+- Series B / growth stage: lighter process but still has security review, maybe SOC2 in progress
+- Startup: minimal process, mostly just engineering work
+
+Respond ONLY with valid JSON matching this schema:
+{
+  "profile": "the enterprise profile",
+  "summary": {
+    "total_dependencies": number,
+    "critical_path_days": number,
+    "total_stakeholders": ["role1", "role2"],
+    "overall_risk": "low|medium|high|critical",
+    "executive_summary": "2-3 sentence summary"
+  },
+  "additional_requirements": ["extra things this enterprise type needs"],
+  "dependency_analysis": [
+    {
+      "dependency": "name",
+      "type": "type",
+      "required": true,
+      "estimated_days": number,
+      "stakeholders": ["role1"],
+      "risks": ["risk1"],
+      "recommendation": "actionable advice"
+    }
+  ]
+}`;
+// Fallback estimation tables when no API key
+const ESTIMATES = {
+    api: {
+        baseDays: 5,
+        stakeholders: ["API platform team", "Security review"],
+        risks: ["Rate limiting", "API versioning changes", "Credential rotation"],
+    },
+    database: {
+        baseDays: 8,
+        stakeholders: ["DBA team", "Data governance"],
+        risks: ["Schema migration conflicts", "Performance impact", "Data residency"],
+    },
+    auth: {
+        baseDays: 10,
+        stakeholders: ["Identity team", "Security architect"],
+        risks: ["SSO configuration complexity", "Token lifecycle management"],
+    },
+    storage: {
+        baseDays: 4,
+        stakeholders: ["Cloud infrastructure team"],
+        risks: ["Storage cost scaling", "Data retention policies"],
+    },
+    network: {
+        baseDays: 7,
+        stakeholders: ["Network security", "Firewall team"],
+        risks: ["Firewall rule approval delays", "VPN/private link setup"],
+    },
+    secret: {
+        baseDays: 3,
+        stakeholders: ["Security operations", "Vault admin"],
+        risks: ["Secret rotation automation", "Access audit requirements"],
+    },
+    approval: {
+        baseDays: 12,
+        stakeholders: ["Designated approver", "Legal (if PII involved)"],
+        risks: ["Approval bottlenecks", "Re-approval on scope changes"],
+    },
+    compliance: {
+        baseDays: 20,
+        stakeholders: ["Compliance officer", "Legal", "External auditor"],
+        risks: ["Audit timeline uncertainty", "Control gap remediation"],
+    },
+};
+const PROFILE_MULTIPLIERS = {
+    "fortune 500": {
+        multiplier: 2.5,
+        extras: ["Change Advisory Board review", "Vendor risk assessment", "Procurement cycle"],
+    },
+    "fortune 500 bank": {
+        multiplier: 3.0,
+        extras: ["OCC/FFIEC regulatory review", "Third-party risk management", "Model risk assessment"],
+    },
+    enterprise: {
+        multiplier: 2.0,
+        extras: ["Change management process", "Architecture review board"],
+    },
+    "series b": {
+        multiplier: 1.2,
+        extras: ["Lightweight security review"],
+    },
+    "series b fintech": {
+        multiplier: 1.5,
+        extras: ["PCI-DSS considerations", "State licensing check"],
+    },
+    startup: {
+        multiplier: 1.0,
+        extras: [],
+    },
+};
+function matchProfile(profile) {
+    const lower = profile.toLowerCase();
+    for (const [key, val] of Object.entries(PROFILE_MULTIPLIERS)) {
+        if (lower.includes(key))
+            return val;
+    }
+    return { multiplier: 1.5, extras: ["Standard enterprise review"] };
+}
+function fallbackSimulation(manifest, profile) {
+    const { multiplier, extras } = matchProfile(profile);
+    const deps = manifest.dependencies || [];
+    const analyses = deps.map((dep) => {
+        const est = ESTIMATES[dep.type] || ESTIMATES["api"];
+        const days = Math.ceil(est.baseDays * multiplier);
+        return {
+            dependency: dep.name,
+            type: dep.type,
+            required: dep.required ?? true,
+            estimated_days: days,
+            stakeholders: est.stakeholders,
+            risks: est.risks,
+            recommendation: days > 15
+                ? "Start early — this is on the critical path"
+                : days > 7
+                    ? "Plan ahead — requires coordination"
+                    : "Straightforward — can parallelize",
+        };
+    });
+    const totalDays = Math.max(...analyses.map((a) => a.estimated_days), 0);
+    const parallelDays = Math.ceil(totalDays * 1.2);
+    return {
+        profile,
+        summary: {
+            total_dependencies: deps.length,
+            critical_path_days: parallelDays,
+            total_stakeholders: [...new Set(analyses.flatMap((a) => a.stakeholders)), ...extras],
+            overall_risk: manifest.risk_level || "medium",
+        },
+        additional_requirements: extras,
+        dependency_analysis: analyses,
+    };
+}
+async function llmSimulation(client, manifest, manifestYaml, profile) {
+    const response = await client.messages.create({
+        model: "claude-sonnet-4-5-20250929",
+        max_tokens: 4096,
+        messages: [
+            {
+                role: "user",
+                content: `Enterprise profile: ${profile}\n\nAgent manifest (interf.yaml):\n\`\`\`yaml\n${manifestYaml}\n\`\`\`\n\nProduce the deployment simulation JSON.`,
+            },
+        ],
+        system: SIMULATION_PROMPT,
+    });
+    const text = response.content.find((b) => b.type === "text");
+    if (!text || text.type !== "text")
+        throw new Error("No text in LLM response");
+    // Extract JSON from response (handle markdown code blocks)
+    let jsonStr = text.text.trim();
+    const fenceMatch = jsonStr.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (fenceMatch)
+        jsonStr = fenceMatch[1].trim();
+    return JSON.parse(jsonStr);
+}
+export function createServer() {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        console.error("interf-gateway: WARNING — ANTHROPIC_API_KEY not configured. run_simulation will not work.");
+        console.error("interf-gateway: Set it via: claude mcp add interf-gateway -e ANTHROPIC_API_KEY=sk-... -- npx -y @interf/gateway");
+    }
+    const client = apiKey ? new Anthropic({ apiKey }) : null;
+    const server = new McpServer({
+        name: "interf-gateway",
+        version: "0.0.1",
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    server.registerTool("get_protocol_guidance", {
+        description: "Returns the full Interf Protocol specification, including the interf.yaml schema, " +
+            "canonical dependency types, and step-by-step instructions for generating a manifest. " +
+            "Call this first before helping a user create their agent readiness spec.",
+        inputSchema: {},
+    }, async () => ({
+        content: [{ type: "text", text: PROTOCOL_GUIDANCE }],
+    }));
+    server.registerTool("run_simulation", {
+        description: "Simulates enterprise deployment of an agent by analyzing its interf.yaml manifest " +
+            "against target enterprise profiles. Returns per-dependency timeline estimates, " +
+            "stakeholder requirements, risks, and recommendations. " +
+            "If ANTHROPIC_API_KEY is configured, uses LLM for rich analysis. Otherwise returns heuristic estimates.",
+        inputSchema: {
+            manifest: z
+                .string()
+                .describe("The interf.yaml manifest content as a YAML string"),
+            enterprise_profiles: z
+                .array(z.string())
+                .describe('Target enterprise profiles to simulate against, e.g. ["Fortune 500 bank", "Series B fintech"]'),
+        },
+    }, async ({ manifest, enterprise_profiles }) => {
+        if (!client) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: ANTHROPIC_API_KEY not configured. Cannot run simulation.\n\nTo fix, re-add the MCP server with your API key:\n  claude mcp add interf-gateway -e ANTHROPIC_API_KEY=sk-... -- npx -y @interf/gateway",
+                    },
+                ],
+            };
+        }
+        let parsed;
+        try {
+            parsed = YAML.parse(manifest);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: Invalid YAML in manifest. Please check the syntax.",
+                    },
+                ],
+            };
+        }
+        if (!parsed.dependencies || parsed.dependencies.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: Manifest has no dependencies. Add at least one dependency to simulate.",
+                    },
+                ],
+            };
+        }
+        const results = [];
+        for (const profile of enterprise_profiles) {
+            try {
+                const result = await llmSimulation(client, parsed, manifest, profile);
+                results.push(result);
+            }
+            catch (err) {
+                console.error(`interf-gateway: LLM simulation failed for "${profile}":`, err);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: Simulation failed for profile "${profile}". Check ANTHROPIC_API_KEY is valid.`,
+                        },
+                    ],
+                };
+            }
+        }
+        const output = {
+            agent: parsed.name || "unnamed-agent",
+            version: parsed.version || "0.0.0",
+            simulations: results,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(output, null, 2),
+                },
+            ],
+        };
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@interf/gateway",
+  "version": "0.0.1",
+  "description": "Agent Readiness Protocol - MCP server for coding agents to understand enterprise integration requirements",
+  "type": "module",
+  "bin": {
+    "interf-gateway": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "yaml": "^2.7.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  }
+}