opensecrets-mcp 1.0.0

package/README.md

@@ -0,0 +1,27 @@
+# OpenSecrets MCP
+
+MCP server for OpenSecrets: money in U.S. politics. Needs a free API key.
+
+Pairs well with `fec-mcp`, `congress-gov-mcp`, and `govtrack-mcp`.
+
+## Quick start
+
+Get a key at https://www.opensecrets.org/api/ (free), then:
+
+```bash
+export OPENSECRETS_API_KEY=your_key_here
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `search_candidates`: Candidates by name with party/state/chamber.
+- `candidate_summary`: Raised, spent, cash, debt per cycle.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. Your key stays local and is only sent to OpenSecrets. Read-only.

package/dist/api.d.ts

@@ -0,0 +1,12 @@
+export declare class OpenSecretsError extends Error {
+}
+export interface Candidate {
+    id?: string;
+    name?: string;
+    party?: string;
+    state?: string;
+    chamber?: string;
+}
+export declare function searchCandidates(query: string, cycle?: string): Promise<Candidate[]>;
+export declare function candidateSummary(cid: string, cycle?: string): Promise<string>;
+export declare function formatCandidate(c: Candidate, index?: number): string;

package/dist/api.js

@@ -0,0 +1,63 @@
+/**
+ * OpenSecrets API client. Needs OPENSECRETS_API_KEY
+ * (free at https://www.opensecrets.org/api/).
+ * Docs: https://www.opensecrets.org/resources/create/apis.php
+ */
+const BASE = "https://www.opensecrets.org/api";
+export class OpenSecretsError extends Error {
+}
+function apiKey() {
+    const k = process.env.OPENSECRETS_API_KEY;
+    if (!k)
+        throw new OpenSecretsError("Set OPENSECRETS_API_KEY first (free at opensecrets.org/api).");
+    return k;
+}
+async function getJson(params) {
+    const qs = new URLSearchParams({ ...params, apikey: apiKey(), output: "json" }).toString();
+    const res = await fetch(`${BASE}/?${qs}`, {
+        headers: { "User-Agent": "opensecrets-mcp/1.0", Accept: "application/json" },
+        signal: AbortSignal.timeout(25000),
+    });
+    if (res.status === 401 || res.status === 403)
+        throw new OpenSecretsError("OpenSecrets refused (401/403). Check API key.");
+    if (!res.ok)
+        throw new OpenSecretsError(`OpenSecrets error ${res.status}`);
+    return (await res.json());
+}
+export async function searchCandidates(query, cycle = "2024") {
+    if (!query.trim())
+        throw new OpenSecretsError("Query is empty.");
+    const data = await getJson({ method: "getLegislators", id: query.trim() });
+    const rows = Array.isArray(data.response?.legislator) ? data.response.legislator : [];
+    const attrs = (r) => r["@attributes"] ?? {};
+    return rows.slice(0, 10).map((r) => {
+        const a = attrs(r);
+        return {
+            id: a.cid,
+            name: `${a.firstname ?? ""} ${a.lastname ?? ""}`.trim() || undefined,
+            party: a.party,
+            state: a.state,
+            chamber: a.chamber,
+        };
+    });
+}
+export async function candidateSummary(cid, cycle = "2024") {
+    if (!cid.trim())
+        throw new OpenSecretsError("Candidate id is empty.");
+    const data = await getJson({ method: "candSummary", cid: cid.trim(), cycle });
+    const a = data.response?.summary?.["@attributes"] ?? {};
+    if (!a.candidate_name)
+        throw new OpenSecretsError(`No summary for ${cid} in ${cycle}.`);
+    return [
+        `${a.candidate_name ?? cid}${a.party ? ` (${a.party}-${a.state ?? "?"})` : ""} — ${cycle} cycle`,
+        `Raised: $${Number(a.total ?? 0).toLocaleString()}`,
+        `Spent: $${Number(a.spent ?? 0).toLocaleString()}`,
+        `Cash on hand: $${Number(a.cash_on_hand ?? 0).toLocaleString()}`,
+        `Debt: $${Number(a.debt ?? 0).toLocaleString()}`,
+        a.source ? `Source: ${a.source}` : "",
+    ].filter(Boolean).join("\n");
+}
+export function formatCandidate(c, index) {
+    const prefix = index !== undefined ? `${index + 1}. ` : "";
+    return `${prefix}[${c.id ?? "?"}] ${c.name ?? "(unnamed)"}${c.party ? ` (${c.party}${c.state ? `-${c.state}` : ""})` : ""}${c.chamber ? ` — ${c.chamber}` : ""}`;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,54 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { candidateSummary, formatCandidate, OpenSecretsError, searchCandidates } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "opensecrets-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_candidates", {
+        title: "Search candidates",
+        description: "Find federal candidates by name fragment: party, state, chamber, CRP id.",
+        inputSchema: z.object({
+            query: z.string().describe("Name fragment, e.g. 'Smith'"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ query }) => {
+        try {
+            const rows = await searchCandidates(query);
+            if (rows.length === 0)
+                return text(`No candidates match "${query}".`);
+            return text(rows.map((c, i) => formatCandidate(c, i)).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("candidate_summary", {
+        title: "Money summary",
+        description: "Raised, spent, cash on hand and debt for one candidate and cycle.",
+        inputSchema: z.object({
+            cid: z.string().describe("CRP candidate id, e.g. 'N00007360' (use search_candidates)"),
+            cycle: z.string().default("2024").describe("Election cycle, e.g. '2024'"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ cid, cycle }) => {
+        try {
+            return text(await candidateSummary(cid, cycle));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof OpenSecretsError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "opensecrets-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for OpenSecrets: money in U.S. politics. Needs a free API key.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/opensecrets-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+  },
+  "bin": {
+    "opensecrets-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "opensecrets",
+    "politics",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}