partnership_synergies

Instructions

Implementation Reference

• src/tools/partnership-synergies.ts:136-138 (handler)

  The handler function that executes the partnership_synergies tool logic by calling the Gapup API endpoint 'partnership-synergies' with the input and optional AbortSignal.

  export async function handle(input: unknown, signal?: AbortSignal): Promise<unknown> {
    return callGapupEndpoint("partnership-synergies", input, signal);
  }

• src/tools/partnership-synergies.ts:3-134 (schema)

  The full tool definition including name ('partnership_synergies'), description, inputSchema (selfCompany, strategicAxis, constraints, currentPartnerships, focus), outputSchema, and annotations.

  export const tool = {
    name: "partnership_synergies",
    description:
      "Identify and rank strategic partnership opportunities for a company. Returns 5-12 high-fit partnership targets, each scored on revenue lift, time-to-impact, integration complexity and regulatory risk, with a rationale and a recommended first-step outreach playbook. When to use this tool: the user wants business-development or alliance ideas, or M&A target screening before deeper due diligence. Inputs: the user's own company and the strategic axis to unlock through partnership (e.g. enter a new market via distribution, add AI infrastructure without rebuilding). Delivered by Antoine, the AI CSO of the Gapup portfolio.",
    inputSchema: {
      type: "object",
      properties: {
        selfCompany: {
          type: "object",
          properties: {
            name: { type: "string", minLength: 2, maxLength: 120 },
            url: { type: "string", format: "uri" },
            pitch: { type: "string", minLength: 10, maxLength: 600 },
            stage: {
              type: "string",
              enum: ["pre-seed", "seed", "series-a", "series-b", "series-c", "growth", "public"],
            },
            arrEur: { type: "number", minimum: 0 },
          },
          required: ["name", "pitch"],
        },
        strategicAxis: {
          type: "string",
          minLength: 20,
          maxLength: 800,
          description: "What strategic axis to unlock through partnership (e.g. 'enter US market via distribution', 'leverage AI infra without rebuild')",
        },
        constraints: {
          type: "object",
          properties: {
            budgetCeilingEur: { type: "number", minimum: 0 },
            timeWindow: { type: "string", enum: ["3mo", "6mo", "12mo", "24mo"] },
            regulatoryHotZones: { type: "array", items: { type: "string" } },
            mustNotCompeteWith: { type: "array", items: { type: "string" } },
          },
        },
        currentPartnerships: {
          type: "array",
          items: { type: "string" },
          maxItems: 20,
          description: "Existing alliances to factor in",
        },
        focus: {
          type: "string",
          maxLength: 800,
        },
      },
      required: ["selfCompany", "strategicAxis"],
    },
    outputSchema: {
      type: "object",
      properties: {
        executiveSummary: {
          type: "string",
          description: "Board-ready partnership opportunity overview",
        },
        partnershipTargets: {
          type: "array",
          description: "5-12 ranked partnership targets",
          items: {
            type: "object",
            properties: {
              rank: { type: "integer" },
              partnerName: { type: "string" },
              partnerUrl: { type: "string" },
              partnershipType: { type: "string", description: "e.g. distribution, technology, co-marketing, OEM, M&A" },
              revenueLiftScore: { type: "number", minimum: 0, maximum: 10 },
              timeToImpact: { type: "string", enum: ["3mo", "6mo", "12mo", "24mo"] },
              integrationComplexity: { type: "string", enum: ["low", "medium", "high"] },
              regulatoryRisk: { type: "string", enum: ["low", "medium", "high"] },
              rationale: { type: "string" },
              outreachPlaybook: {
                type: "object",
                properties: {
                  firstStep: { type: "string" },
                  keyContact: { type: "string" },
                  openingAngle: { type: "string" },
                },
                required: ["firstStep", "openingAngle"],
              },
            },
            required: ["rank", "partnerName", "partnershipType", "revenueLiftScore", "rationale"],
          },
        },
        kpis: {
          type: "array",
          description: "3-5 headline KPI bubbles",
          items: {
            type: "object",
            properties: {
              label: { type: "string" },
              value: { type: "string" },
              trend: { type: "string", enum: ["up", "down", "stable"] },
            },
            required: ["label", "value"],
          },
        },
        recommendations: {
          type: "array",
          description: "Prioritised next steps",
          items: {
            type: "object",
            properties: {
              action: { type: "string" },
              horizon: { type: "string" },
              expectedImpact: { type: "string" },
            },
            required: ["action", "horizon"],
          },
        },
        sources: {
          type: "array",
          items: {
            type: "object",
            properties: {
              url: { type: "string" },
              excerpt: { type: "string" },
            },
            required: ["url"],
          },
        },
      },
      required: ["executiveSummary", "partnershipTargets"],
    },
    annotations: {
      readOnlyHint: true,
      idempotentHint: true,
      destructiveHint: false,
      openWorldHint: true,
      title: "Strategic Partnership Synergies",
    },
  } as const;

• src/client.ts:26-86 (helper)

  The shared HTTP client helper function 'callGapupEndpoint' used by the handler to POST to the Gapup API. It handles auth, rate limiting, and error responses.

  export async function callGapupEndpoint(
    slug: string,
    input: unknown,
    signal?: AbortSignal
  ): Promise<unknown> {
    const apiKey = process.env.GAPUP_API_KEY;
    if (!apiKey) {
      throw new GapupAuthError(
        "GAPUP_API_KEY environment variable required. Get a free tier key (100 calls/mo) at https://hub.gapup.io/agents-api/onboard"
      );
    }
  
    const res = await fetch(`${HUB_BASE_URL}/api/agent/${slug}`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": apiKey,
        "Accept": "application/json",
        "User-Agent": "@gapup/mcp-knowledge/0.1.0",
      },
      body: JSON.stringify(input),
      signal,
    });
  
    if (res.status === 401) {
      throw new GapupAuthError(
        "Invalid or missing GAPUP_API_KEY. Verify your key at https://hub.gapup.io/agents-api/onboard"
      );
    }
  
    if (res.status === 402) {
      const body = await res.text().catch(() => "");
      throw new GapupAuthError(
        `Free tier quota exhausted or paid auth required. Upgrade at https://hub.gapup.io/agents-api (received 402: ${body.slice(0, 120)})`
      );
    }
  
    if (res.status === 404) {
      throw new GapupApiError(
        404,
        `Endpoint '${slug}' not found — check GAPUP_API_BASE_URL or update the package (npm update @gapup/mcp-knowledge)`
      );
    }
  
    if (res.status === 429) {
      const retryAfter = res.headers.get("Retry-After");
      const retryMsg = retryAfter ? ` Retry after ${retryAfter} seconds.` : "";
      const body = await res.text().catch(() => "");
      throw new GapupApiError(
        429,
        `Rate limit exceeded.${retryMsg} Upgrade your plan at https://hub.gapup.io/agents-api (received: ${body.slice(0, 100)})`
      );
    }
  
    if (!res.ok) {
      const body = await res.text().catch(() => "");
      throw new GapupApiError(res.status, body);
    }
  
    return res.json();
  }

• src/index.ts:21-42 (registration)

  The import and registration of the partnership_synergies tool in the TOOLS array, which gets exposed via the MCP ListToolsRequestSchema handler.

  import { tool as competitorIntelTool, handle as competitorIntelHandle } from "./tools/competitor-intel.js";
  import { tool as trendWatcherTool, handle as trendWatcherHandle } from "./tools/trend-watcher.js";
  import { tool as partnershipTool, handle as partnershipHandle } from "./tools/partnership-synergies.js";
  import { tool as pitchDeckTool, handle as pitchDeckHandle } from "./tools/pitch-deck-storyline.js";
  import { tool as carbonTool, handle as carbonHandle } from "./tools/carbon-footprint-calculator.js";
  
  type ToolHandle = (input: unknown, signal?: AbortSignal) => Promise<unknown>;
  type ToolDef = {
    name: string;
    description: string;
    inputSchema: object;
    outputSchema?: object;
    annotations?: object;
  };
  
  const TOOLS: Array<{ def: ToolDef; handle: ToolHandle }> = [
    { def: competitorIntelTool, handle: competitorIntelHandle },
    { def: trendWatcherTool, handle: trendWatcherHandle },
    { def: partnershipTool, handle: partnershipHandle },
    { def: pitchDeckTool, handle: pitchDeckHandle },
    { def: carbonTool, handle: carbonHandle },
  ];