contact_depscope

Instructions

Implementation Reference

• mcp-server/tools.js:585-622 (handler)

  Handler for the contact_depscope tool in the handleToolCall dispatcher. Routes to /api/anomaly for 'anomaly' kind, or /api/contact otherwise. Also handles the back-compat alias report_anomaly.

  case "contact_depscope": {
    if (args.kind === "anomaly") {
      const body = JSON.stringify({
        tool_called: args.tool_called,
        ecosystem: args.ecosystem || "",
        package: args.package || "",
        version: args.version || "",
        observed: args.observed,
        expected: args.expected,
        evidence_url: args.evidence_url || "",
        source: "mcp",
      });
      const res = await fetch(`${API_BASE}/api/anomaly`, {
        method: "POST",
        headers: { "Content-Type": "application/json", "X-Depscope-Source": "mcp", "X-MCP-Tool": name },
        body,
      });
      if (!res.ok) return fail(`contact_depscope(anomaly) failed: ${res.status} ${await res.text().catch(()=>"")}`);
      return ok(await res.json());
    }
    const body = JSON.stringify({
      email: args.email,
      subject: args.subject,
      body: args.body,
      type: args.kind || args.type || "other",
      name: args.name || "",
      company: args.company || "",
      source: "mcp",
      consent: true,
    });
    const res = await fetch(`${API_BASE}/api/contact`, {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-Depscope-Source": "mcp", "X-MCP-Tool": name },
      body,
    });
    if (!res.ok) return fail(`contact_depscope failed: ${res.status} ${await res.text().catch(()=>"")}`);
    return ok(await res.json());
  }

• mcp-server/tools.js:490-520 (schema)

  Tool definition/schema for contact_depscope in the TOOLS array. Defines name, description, annotations (non-idempotent), and inputSchema with properties: kind, email, subject, body, name, company, tool_called, ecosystem, package, version, observed, expected, evidence_url.

  // ── 8. Feedback channel (NOT idempotent — creates a ticket) ─────────
  {
    name: "contact_depscope",
    description:
      "Inbound ticket: bug/listing/security/anomaly/partnership. USE WHEN: reporting wrong data (`bug`), requesting a new pkg/ecosystem index (`listing`), disclosing a DepScope security issue (`security`), flagging a concrete mismatch in another tool's output vs. authoritative source (`anomaly` — provide tool_called+observed+expected), or partnership/press (`partnership`). RETURNS: {ticket_id} or {anomaly_id}.",
    annotations: {
      title: "contact_depscope",
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: false,
      openWorldHint: true,
    },
    inputSchema: {
      type: "object",
      properties: {
        kind: { type: "string", enum: ["bug","listing","security","anomaly","partnership"], description: "Ticket category. `anomaly` routes to structured anomaly triage (requires tool_called/observed/expected)." },
        email: { type: "string", description: "Reply-to email of the requester (required for bug/listing/security/partnership)." },
        subject: { type: "string", description: "Short subject line (3-200 chars)." },
        body: { type: "string", description: "Message body (10-8000 chars). Be specific: include package name, ecosystem, error trace, repro steps when applicable." },
        name: { type: "string", description: "Sender display name (optional)." },
        company: { type: "string", description: "Company / organization (optional)." },
        tool_called: { type: "string", description: "For kind=anomaly: DepScope tool that produced the anomaly (e.g. check_package, get_migration_path)." },
        ecosystem: { type: "string", description: "For kind=anomaly: ecosystem of the involved package, if any." },
        package: { type: "string", description: "For kind=anomaly: package name involved, if any." },
        version: { type: "string", description: "For kind=anomaly: package version involved, if any." },
        observed: { type: "string", description: "For kind=anomaly: what DepScope returned (1-1500 chars)." },
        expected: { type: "string", description: "For kind=anomaly: what you expected to see (1-1500 chars). Be concrete." },
        evidence_url: { type: "string", description: "For kind=anomaly: URL to authoritative source (registry page, GHSA, CVE, repo, ...) supporting your expectation." },
      },
    },
  },

• mcp-server/index.js:16-19 (registration)

  Registration via ListToolsRequestSchema (returns TOOLS array) and CallToolRequestSchema (calls handleToolCall) in stdio entry point.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
  server.setRequestHandler(CallToolRequestSchema, async (req) =>
    handleToolCall(req.params.name, req.params.arguments || {})
  );

• mcp-server/http-server.js:29-32 (registration)

  Registration via ListToolsRequestSchema (returns TOOLS array) and CallToolRequestSchema (calls handleToolCall) in Streamable HTTP entry point.

  s.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
  s.setRequestHandler(CallToolRequestSchema, async (req) =>
    handleToolCall(req.params.name, req.params.arguments || {})
  );

• mcp-server/tools.js:557-563 (helper)

  Helper functions ok() and fail() used by the handler to format success/error responses.

  function ok(data) {
    const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
    return { content: [{ type: "text", text }] };
  }
  function fail(message) {
    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
  }