@donmorton/context-mcp-bridge 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# Context MCP Bridge
+
+Generic stdio MCP bridge for a hosted service. The server does not contain API secrets; it connects to a hosted API with credentials provided through environment variables.
+
+## Required Environment
+
+- `SERVICE_API_URL`: hosted service URL
+- `SERVICE_API_TOKEN`: service API token
+
+## Claude Config
+
+Use `npx`/`pnpm dlx` from the same Node install that Claude can launch. If Node was installed with `nvm`, GUI apps may need the absolute path to `npx`.
+
+```json
+{
+  "mcpServers": {
+    "context": {
+      "command": "/absolute/path/to/npx",
+      "args": ["-y", "@donmorton/context-mcp-bridge"],
+      "env": {
+        "SERVICE_API_URL": "https://YOUR-HOSTED-SERVICE-URL",
+        "SERVICE_API_TOKEN": "YOUR-SERVICE-API-TOKEN"
+      }
+    }
+  }
+}
+```
+
+For a global install, use `npm install -g @donmorton/context-mcp-bridge` and set `command` to the absolute path of the installed `context-mcp-bridge` binary.

package/dist/src/api.js

@@ -0,0 +1,103 @@
+export class ServiceApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ServiceApiError";
+    }
+}
+export class ServiceApiClient {
+    baseUrl;
+    apiToken;
+    fetchImpl;
+    constructor(baseUrl, apiToken, fetchImpl = fetch) {
+        this.baseUrl = baseUrl;
+        this.apiToken = apiToken;
+        this.fetchImpl = fetchImpl;
+    }
+    async getHealth() {
+        return this.request("/api/health", { auth: false });
+    }
+    async get(path, query) {
+        return this.request(withQuery(path, query));
+    }
+    async post(path, body) {
+        return this.request(path, {
+            method: "POST",
+            ...(body === undefined ? {} : { body: JSON.stringify(body) })
+        });
+    }
+    async patch(path, body) {
+        return this.request(path, {
+            method: "PATCH",
+            ...(body === undefined ? {} : { body: JSON.stringify(body) })
+        });
+    }
+    async delete(path) {
+        return this.request(path, { method: "DELETE" });
+    }
+    async getCompany(companyKey) {
+        return this.request(`/api/companies/${encodeURIComponent(companyKey)}`);
+    }
+    async enrichCompanyContacts(companyKey) {
+        return this.post(`/api/companies/${encodeURIComponent(companyKey)}/apollo/enrich`);
+    }
+    async removeCompanyContacts(companyKey) {
+        return this.delete(`/api/companies/${encodeURIComponent(companyKey)}/contact`);
+    }
+    async request(path, options = {}) {
+        const url = new URL(path, stripTrailingSlash(this.baseUrl));
+        const { auth = true, ...requestOptions } = options;
+        const headers = new Headers(options.headers);
+        if (auth)
+            headers.set("Authorization", `Bearer ${this.apiToken}`);
+        if (options.body !== undefined && !headers.has("Content-Type"))
+            headers.set("Content-Type", "application/json");
+        const response = await this.fetchImpl(url.toString(), {
+            ...requestOptions,
+            headers
+        });
+        if (!response.ok) {
+            const body = await safeReadText(response);
+            const detail = body || response.statusText || "Request failed";
+            throw new ServiceApiError(response.status, `Service API request failed with ${response.status}: ${detail}`);
+        }
+        return (await response.json());
+    }
+}
+export function createServiceApiClientFromEnv(env = process.env, fetchImpl) {
+    const baseUrl = env.SERVICE_API_URL?.trim();
+    const apiToken = env.SERVICE_API_TOKEN?.trim();
+    if (!baseUrl)
+        throw new Error("SERVICE_API_URL is required");
+    if (!apiToken)
+        throw new Error("SERVICE_API_TOKEN is required");
+    return new ServiceApiClient(baseUrl, apiToken, fetchImpl);
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "";
+    }
+}
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function withQuery(path, query = {}) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                params.append(key, String(item));
+        }
+        else {
+            params.set(key, String(value));
+        }
+    }
+    const text = params.toString();
+    return text ? `${path}?${text}` : path;
+}

package/dist/src/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createContextMcpServer } from "./server.js";
+async function main() {
+    const server = createContextMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Context MCP server failed";
+    console.error(message);
+    process.exit(1);
+});

package/dist/src/server.js

@@ -0,0 +1,223 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { createServiceApiClientFromEnv } from "./api.js";
+import { enrichCompanyContactsSafely, refreshCompanyContacts, removeCompanyContacts, contextCapabilities } from "./tools.js";
+export function createContextMcpServer(options = {}) {
+    const server = new McpServer({
+        name: "context-bridge",
+        version: "0.1.0"
+    });
+    registerContextTools(server, options.clientFactory ?? createServiceApiClientFromEnv);
+    return server;
+}
+export function registerContextTools(server, clientFactory) {
+    server.registerTool("context_health", {
+        description: "Check whether the hosted service API is reachable.",
+        inputSchema: {}
+    }, async () => textResult(await clientFactory().getHealth()));
+    server.registerTool("context_capabilities", {
+        description: "List Context MCP capabilities and contact-enrichment cost guidance.",
+        inputSchema: {}
+    }, async () => textResult(contextCapabilities()));
+    server.registerTool("context_list_jobs", {
+        description: "List service jobs with optional filters.",
+        inputSchema: jobListSchema
+    }, async (input) => textResult(await clientFactory().get("/api/jobs", cleanQuery(input))));
+    server.registerTool("context_get_job", {
+        description: "Get one service job by id.",
+        inputSchema: {
+            id: z.string().min(1)
+        }
+    }, async ({ id }) => textResult(await clientFactory().get(`/api/jobs/${encodeURIComponent(id)}`)));
+    server.registerTool("context_list_companies", {
+        description: "List companies aggregated from service jobs.",
+        inputSchema: companyListSchema
+    }, async (input) => textResult(await clientFactory().get("/api/companies", cleanQuery(input))));
+    server.registerTool("context_get_company", {
+        description: "Get a company profile, including contact enrichment status when available.",
+        inputSchema: {
+            companyKey: z.string().min(1)
+        }
+    }, async ({ companyKey }) => textResult(await clientFactory().get(`/api/companies/${encodeURIComponent(companyKey)}`)));
+    server.registerTool("context_get_analytics", {
+        description: "Get service analytics with optional filters.",
+        inputSchema: analyticsSchema
+    }, async (input) => textResult(await clientFactory().get("/api/analytics", cleanQuery(input))));
+    server.registerTool("context_list_saved_searches", {
+        description: "List saved Google Jobs searches.",
+        inputSchema: {}
+    }, async () => textResult(await clientFactory().get("/api/searches")));
+    server.registerTool("context_list_fetch_runs", {
+        description: "List recent fetch runs.",
+        inputSchema: {}
+    }, async () => textResult(await clientFactory().get("/api/fetch-runs")));
+    server.registerTool("context_get_settings", {
+        description: "Get service settings.",
+        inputSchema: {}
+    }, async () => textResult(await clientFactory().get("/api/settings")));
+    server.registerTool("context_get_search_suggestions", {
+        description: "Get suggested service searches and Google Jobs filter guidance.",
+        inputSchema: {}
+    }, async () => textResult(await clientFactory().get("/api/search-suggestions")));
+    server.registerTool("context_trigger_fetch", {
+        description: "Trigger all enabled searches, one saved search, or a list of saved searches.",
+        inputSchema: {
+            savedSearchId: z.string().min(1).optional(),
+            savedSearchIds: z.array(z.string().min(1)).min(1).optional()
+        }
+    }, async (input) => textResult(await clientFactory().post("/api/fetch-runs", cleanBody(input))));
+    server.registerTool("context_review_job", {
+        description: "Update a job review status.",
+        inputSchema: {
+            id: z.string().min(1),
+            status: reviewStatusSchema,
+            reason: z.string().max(120).optional().nullable()
+        }
+    }, async ({ id, ...body }) => textResult(await clientFactory().patch(`/api/jobs/${encodeURIComponent(id)}/review`, cleanBody(body))));
+    server.registerTool("context_enrich_job", {
+        description: "Run job-level enrichment for source/place/pay/scoring data.",
+        inputSchema: {
+            id: z.string().min(1)
+        }
+    }, async ({ id }) => textResult(await clientFactory().post(`/api/jobs/${encodeURIComponent(id)}/enrich`)));
+    server.registerTool("context_retry_job_place", {
+        description: "Retry Google Places enrichment for a job.",
+        inputSchema: {
+            id: z.string().min(1)
+        }
+    }, async ({ id }) => textResult(await clientFactory().post(`/api/jobs/${encodeURIComponent(id)}/place/retry`)));
+    server.registerTool("context_update_job_place", {
+        description: "Select, manually set, or clear the place attached to a job.",
+        inputSchema: {
+            id: z.string().min(1),
+            action: z.enum(["select_candidate", "manual", "clear"]),
+            cid: z.string().optional().nullable(),
+            title: z.string().min(1).optional(),
+            address: z.string().min(1).optional(),
+            phoneNumber: z.string().optional().nullable(),
+            website: z.string().optional().nullable(),
+            latitude: z.number().optional().nullable(),
+            longitude: z.number().optional().nullable()
+        }
+    }, async ({ id, ...body }) => textResult(await clientFactory().patch(`/api/jobs/${encodeURIComponent(id)}/place`, cleanBody(body))));
+    server.registerTool("context_create_saved_search", {
+        description: "Create a saved Google Jobs search.",
+        inputSchema: savedSearchSchema
+    }, async (input) => textResult(await clientFactory().post("/api/searches", cleanBody(input))));
+    server.registerTool("context_update_saved_search", {
+        description: "Update a saved Google Jobs search.",
+        inputSchema: {
+            id: z.string().min(1),
+            ...partialSavedSearchSchema
+        }
+    }, async ({ id, ...body }) => textResult(await clientFactory().patch(`/api/searches/${encodeURIComponent(id)}`, cleanBody(body))));
+    server.registerTool("context_bulk_update_searches", {
+        description: "Bulk update enabled saved searches.",
+        inputSchema: {
+            ids: z.array(z.string().min(1)).min(1),
+            maxPages: z.number().int().min(1).max(10).optional(),
+            fetchIntervalDays: fetchIntervalSchema.optional()
+        }
+    }, async (input) => textResult(await clientFactory().patch("/api/searches/bulk", cleanBody(input))));
+    server.registerTool("context_update_settings", {
+        description: "Update service settings.",
+        inputSchema: settingsSchema
+    }, async (input) => textResult(await clientFactory().patch("/api/settings", cleanBody(input))));
+    server.registerTool("context_enrich_company_contacts", {
+        description: "Safely enrich company contacts. Reads cached enrichment first and only performs expensive enrichment when missing or due.",
+        inputSchema: {
+            companyKey: z.string().min(1).describe("Company key from hosted service.")
+        }
+    }, async ({ companyKey }) => textResult(await enrichCompanyContactsSafely(clientFactory(), companyKey)));
+    server.registerTool("context_refresh_company_contacts", {
+        description: "Force-refresh company contact enrichment. Expensive; use only after explicit user confirmation.",
+        inputSchema: {
+            companyKey: z.string().min(1).describe("Company key from hosted service."),
+            confirmExpensive: z.literal(true).describe("Must be true after the user confirms this expensive forced refresh.")
+        }
+    }, async ({ companyKey, confirmExpensive }) => textResult(await refreshCompanyContacts(clientFactory(), { companyKey, confirmExpensive })));
+    server.registerTool("context_remove_company_contacts", {
+        description: "Remove stored contact enrichment for a company.",
+        inputSchema: {
+            companyKey: z.string().min(1).describe("Company key from hosted service.")
+        }
+    }, async ({ companyKey }) => textResult(await removeCompanyContacts(clientFactory(), companyKey)));
+}
+const companySizeSchema = z.enum(["small", "medium", "large", "unknown"]);
+const fetchIntervalSchema = z.union([z.literal(1), z.literal(3), z.literal(7)]);
+const reviewStatusSchema = z.enum(["new", "accepted", "rejected", "needs_review"]);
+const analyticsScopeSchema = z.enum(["qualified", "all"]);
+const payIntervalSchema = z.enum(["hour", "day", "week", "month", "year", "unknown"]);
+const jobListSchema = {
+    status: reviewStatusSchema.optional(),
+    minScore: z.number().int().min(0).max(100).optional(),
+    maxScore: z.number().int().min(0).max(100).optional(),
+    city: z.string().optional(),
+    location: z.string().optional(),
+    company: z.string().optional(),
+    q: z.string().optional(),
+    qMode: z.enum(["contains", "not_contains"]).optional(),
+    enriched: z.enum(["true", "false"]).optional(),
+    companySizes: z.array(companySizeSchema).optional(),
+    dateFrom: z.string().optional(),
+    dateTo: z.string().optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    offset: z.number().int().min(0).optional()
+};
+const companyListSchema = {
+    q: z.string().optional(),
+    minScore: z.number().int().min(0).max(100).optional(),
+    companySizes: z.array(companySizeSchema).optional(),
+    dateFrom: z.string().optional(),
+    dateTo: z.string().optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    offset: z.number().int().min(0).optional()
+};
+const analyticsSchema = {
+    scope: analyticsScopeSchema.optional(),
+    status: reviewStatusSchema.optional(),
+    minScore: z.number().int().min(0).max(100).optional(),
+    city: z.string().optional(),
+    company: z.string().optional(),
+    companySizes: z.array(companySizeSchema).optional(),
+    dateFrom: z.string().optional(),
+    dateTo: z.string().optional(),
+    payInterval: payIntervalSchema.optional()
+};
+const savedSearchSchema = {
+    name: z.string().min(1),
+    query: z.string().min(1),
+    location: z.string().min(1),
+    uds: z.string().min(1).optional().nullable(),
+    gl: z.string().min(2).optional(),
+    hl: z.string().min(2).optional(),
+    googleDomain: z.string().min(1).optional(),
+    maxPages: z.number().int().min(1).max(10).optional(),
+    fetchIntervalDays: fetchIntervalSchema.optional(),
+    enabled: z.boolean().optional()
+};
+const partialSavedSearchSchema = Object.fromEntries(Object.entries(savedSearchSchema).map(([key, value]) => [key, value.optional()]));
+const settingsSchema = {
+    apolloAutoEnrichEnabled: z.boolean().optional(),
+    apolloTargetSmallCompanies: z.boolean().optional(),
+    apolloTargetMediumCompanies: z.boolean().optional(),
+    apolloRefetchIntervalDays: z.number().int().min(1).max(365).optional().nullable(),
+    apolloMaxContacts: z.number().int().min(1).max(6).optional(),
+    apolloRevealEmails: z.boolean().optional()
+};
+function cleanQuery(input) {
+    return cleanBody(input);
+}
+function cleanBody(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
+}
+function textResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2)
+            }
+        ]
+    };
+}

package/dist/src/tools.js

@@ -0,0 +1,94 @@
+export function contextCapabilities() {
+    return {
+        name: "Context MCP Bridge",
+        reads: [
+            "context_health",
+            "context_capabilities",
+            "context_list_jobs",
+            "context_get_job",
+            "context_list_companies",
+            "context_get_company",
+            "context_get_analytics",
+            "context_list_saved_searches",
+            "context_list_fetch_runs",
+            "context_get_settings",
+            "context_get_search_suggestions"
+        ],
+        writes: [
+            "context_trigger_fetch",
+            "context_review_job",
+            "context_enrich_job",
+            "context_retry_job_place",
+            "context_update_job_place",
+            "context_create_saved_search",
+            "context_update_saved_search",
+            "context_bulk_update_searches",
+            "context_update_settings",
+            "context_enrich_company_contacts",
+            "context_refresh_company_contacts",
+            "context_remove_company_contacts"
+        ],
+        guidance: [
+            "Use read tools for lead and company inspection before mutating data.",
+            "Use context_enrich_company_contacts before refresh; it checks cached enrichment and avoids expensive refreshes unless data is missing or due.",
+            "Use context_refresh_company_contacts only after the user explicitly confirms a forced refresh because contact enrichment is expensive.",
+            "Use context_remove_company_contacts only when the user asks to clear stored company contacts."
+        ]
+    };
+}
+export async function enrichCompanyContactsSafely(client, companyKey, now = new Date()) {
+    const profile = await client.getCompany(companyKey);
+    const decision = shouldRunSafeCompanyContactEnrichment(profile, now);
+    if (!decision.run) {
+        return {
+            action: "cached",
+            companyKey,
+            expensiveRequestMade: false,
+            reason: decision.reason,
+            apollo: profile.apollo
+        };
+    }
+    return {
+        action: "enriched",
+        companyKey,
+        expensiveRequestMade: true,
+        reason: decision.reason,
+        apollo: await client.enrichCompanyContacts(companyKey)
+    };
+}
+export async function refreshCompanyContacts(client, input) {
+    if (input.confirmExpensive !== true) {
+        throw new Error("Set confirmExpensive to true only after the user confirms a forced contact enrichment refresh. Enrichment is expensive.");
+    }
+    return {
+        action: "refreshed",
+        companyKey: input.companyKey,
+        expensiveRequestMade: true,
+        reason: "Forced contact enrichment refresh was explicitly confirmed.",
+        apollo: await client.enrichCompanyContacts(input.companyKey)
+    };
+}
+export async function removeCompanyContacts(client, companyKey) {
+    return {
+        action: "removed",
+        companyKey,
+        expensiveRequestMade: false,
+        reason: "Stored company contact enrichment was removed.",
+        apollo: await client.removeCompanyContacts(companyKey)
+    };
+}
+export function shouldRunSafeCompanyContactEnrichment(profile, now = new Date()) {
+    const apollo = profile.apollo;
+    if (!apollo || apollo.status === "NOT_RUN") {
+        return { run: true, reason: "No stored contact enrichment exists for this company." };
+    }
+    if (apollo.nextEligibleAt && Date.parse(apollo.nextEligibleAt) <= now.getTime()) {
+        return { run: true, reason: "Stored contact enrichment is due for refresh." };
+    }
+    return {
+        run: false,
+        reason: apollo.nextEligibleAt
+            ? `Stored contact enrichment is not due until ${apollo.nextEligibleAt}. Use context_refresh_company_contacts only after explicit user confirmation.`
+            : "Stored contact enrichment already exists and automatic refresh is disabled. Use context_refresh_company_contacts only after explicit user confirmation."
+    };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@donmorton/context-mcp-bridge",
+  "version": "0.1.0",
+  "description": "Generic stdio MCP bridge for a hosted service.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "context-mcp-bridge": "dist/src/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "pnpm build",
+    "start": "tsx src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.42"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.1"
+  }
+}