@openar/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API = "https://api.openar.pt";
+async function get(path) {
+    const res = await fetch(`${API}${path}`);
+    if (!res.ok)
+        throw new Error(`API error ${res.status}: ${path}`);
+    return res.json();
+}
+function qs(params) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== "")
+            p.append(k, String(v));
+    }
+    const s = p.toString();
+    return s ? `?${s}` : "";
+}
+const server = new McpServer({
+    name: "openar",
+    version: "0.1.0",
+});
+// ── Meta ────────────────────────────────────────────────────────────────────
+server.tool("get_meta", "Get available filter values: legislaturas, grupos parlamentares, tipos de iniciativa", { legislatura: z.string().optional().describe("Filter grupos/tipos to a specific legislatura") }, async ({ legislatura }) => {
+    const data = await get(`/meta${qs({ legislatura })}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Iniciativas ──────────────────────────────────────────────────────────────
+server.tool("list_iniciativas", "List legislative initiatives with optional filters", {
+    legislatura: z.string().optional().describe("e.g. XVII, XVI"),
+    tipo: z.enum(["R", "P", "J", "D", "S", "A", "I", "C"]).optional()
+        .describe("R=Resolução P=Proposta J=Projeto D=Decreto S=Outros A=Apreciação I=Europeia C=Pergunta"),
+    estado: z.string().optional().describe("e.g. Aprovado, Rejeitado, Caducado"),
+    grupo: z.string().optional().describe("Party abbreviation e.g. PS, PSD, CH"),
+    resultado: z.enum(["aprovado", "rejeitado", "pendente"]).optional(),
+    q: z.string().optional().describe("Search in title"),
+    deputado: z.string().optional().describe("Deputy ID or name (partial match)"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+}, async (params) => {
+    const data = await get(`/iniciativas${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_iniciativa", "Get a legislative initiative with full detail: authors, events, votes, publications", { id: z.number().int().describe("Initiative ID (IniId)") }, async ({ id }) => {
+    const data = await get(`/iniciativas/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Deputados ────────────────────────────────────────────────────────────────
+server.tool("list_deputados", "List MPs with optional filters", {
+    legislatura: z.string().optional().describe("e.g. XVII"),
+    grupo: z.string().optional().describe("Party abbreviation e.g. PS, PSD, BE"),
+    q: z.string().optional().describe("Search by name"),
+    situacao: z.string().optional().describe("Use 'ativo' for current MPs"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+}, async (params) => {
+    const data = await get(`/deputados${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_deputado", "Get an MP with all their mandates and recent initiatives", { id: z.number().int().describe("Deputy ID (DepCadId)") }, async ({ id }) => {
+    const data = await get(`/deputados/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_deputado_atividade", "Get full parliamentary activity for an MP: initiatives, requirements, plenary interventions, committees", {
+    id: z.number().int().describe("Deputy ID (DepCadId)"),
+    legislatura: z.string().optional().describe("e.g. XVII — omit for full history"),
+}, async ({ id, legislatura }) => {
+    const data = await get(`/deputados/${id}/atividade${qs({ legislatura })}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Votações ─────────────────────────────────────────────────────────────────
+server.tool("list_votacoes", "List plenary votes with optional filters", {
+    legislatura: z.string().optional().describe("e.g. XVII"),
+    resultado: z.enum(["Aprovado", "Rejeitado"]).optional(),
+    unanime: z.boolean().optional(),
+    data_inicio: z.string().optional().describe("YYYY-MM-DD"),
+    data_fim: z.string().optional().describe("YYYY-MM-DD"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+}, async (params) => {
+    const data = await get(`/votacoes${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_votacao", "Get a single vote with party breakdown", {
+    id: z.string().describe("Vote ID"),
+    iniciativa_id: z.number().int().describe("Initiative ID (required — vote IDs are unique per initiative)"),
+}, async ({ id, iniciativa_id }) => {
+    const data = await get(`/votacoes/${id}${qs({ iniciativa_id })}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Petições ─────────────────────────────────────────────────────────────────
+server.tool("list_peticoes", "List petitions with optional filters", {
+    legislatura: z.string().optional().describe("e.g. XVII"),
+    situacao: z.string().optional().describe("e.g. Admitida, Arquivada"),
+    q: z.string().optional().describe("Search in subject"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+}, async (params) => {
+    const data = await get(`/peticoes${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_peticao", "Get a petition with committees, rapporteurs, and documents", { id: z.number().int().describe("Petition ID") }, async ({ id }) => {
+    const data = await get(`/peticoes/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@openar/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for openAR — Portuguese parliamentary data",
+  "type": "module",
+  "bin": {
+    "openar-mcp": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "openar",
+    "parlamento",
+    "portugal"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API = "https://api.openar.pt";
+
+async function get<T>(path: string): Promise<T> {
+  const res = await fetch(`${API}${path}`);
+  if (!res.ok) throw new Error(`API error ${res.status}: ${path}`);
+  return res.json() as Promise<T>;
+}
+
+function qs(params: Record<string, string | number | boolean | undefined>): string {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== "") p.append(k, String(v));
+  }
+  const s = p.toString();
+  return s ? `?${s}` : "";
+}
+
+const server = new McpServer({
+  name: "openar",
+  version: "0.1.0",
+});
+
+// ── Meta ────────────────────────────────────────────────────────────────────
+
+server.tool(
+  "get_meta",
+  "Get available filter values: legislaturas, grupos parlamentares, tipos de iniciativa",
+  { legislatura: z.string().optional().describe("Filter grupos/tipos to a specific legislatura") },
+  async ({ legislatura }) => {
+    const data = await get(`/meta${qs({ legislatura })}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// ── Iniciativas ──────────────────────────────────────────────────────────────
+
+server.tool(
+  "list_iniciativas",
+  "List legislative initiatives with optional filters",
+  {
+    legislatura: z.string().optional().describe("e.g. XVII, XVI"),
+    tipo: z.enum(["R", "P", "J", "D", "S", "A", "I", "C"]).optional()
+      .describe("R=Resolução P=Proposta J=Projeto D=Decreto S=Outros A=Apreciação I=Europeia C=Pergunta"),
+    estado: z.string().optional().describe("e.g. Aprovado, Rejeitado, Caducado"),
+    grupo: z.string().optional().describe("Party abbreviation e.g. PS, PSD, CH"),
+    resultado: z.enum(["aprovado", "rejeitado", "pendente"]).optional(),
+    q: z.string().optional().describe("Search in title"),
+    deputado: z.string().optional().describe("Deputy ID or name (partial match)"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+  },
+  async (params) => {
+    const data = await get(`/iniciativas${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "get_iniciativa",
+  "Get a legislative initiative with full detail: authors, events, votes, publications",
+  { id: z.number().int().describe("Initiative ID (IniId)") },
+  async ({ id }) => {
+    const data = await get(`/iniciativas/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// ── Deputados ────────────────────────────────────────────────────────────────
+
+server.tool(
+  "list_deputados",
+  "List MPs with optional filters",
+  {
+    legislatura: z.string().optional().describe("e.g. XVII"),
+    grupo: z.string().optional().describe("Party abbreviation e.g. PS, PSD, BE"),
+    q: z.string().optional().describe("Search by name"),
+    situacao: z.string().optional().describe("Use 'ativo' for current MPs"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+  },
+  async (params) => {
+    const data = await get(`/deputados${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "get_deputado",
+  "Get an MP with all their mandates and recent initiatives",
+  { id: z.number().int().describe("Deputy ID (DepCadId)") },
+  async ({ id }) => {
+    const data = await get(`/deputados/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "get_deputado_atividade",
+  "Get full parliamentary activity for an MP: initiatives, requirements, plenary interventions, committees",
+  {
+    id: z.number().int().describe("Deputy ID (DepCadId)"),
+    legislatura: z.string().optional().describe("e.g. XVII — omit for full history"),
+  },
+  async ({ id, legislatura }) => {
+    const data = await get(`/deputados/${id}/atividade${qs({ legislatura })}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// ── Votações ─────────────────────────────────────────────────────────────────
+
+server.tool(
+  "list_votacoes",
+  "List plenary votes with optional filters",
+  {
+    legislatura: z.string().optional().describe("e.g. XVII"),
+    resultado: z.enum(["Aprovado", "Rejeitado"]).optional(),
+    unanime: z.boolean().optional(),
+    data_inicio: z.string().optional().describe("YYYY-MM-DD"),
+    data_fim: z.string().optional().describe("YYYY-MM-DD"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+  },
+  async (params) => {
+    const data = await get(`/votacoes${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "get_votacao",
+  "Get a single vote with party breakdown",
+  {
+    id: z.string().describe("Vote ID"),
+    iniciativa_id: z.number().int().describe("Initiative ID (required — vote IDs are unique per initiative)"),
+  },
+  async ({ id, iniciativa_id }) => {
+    const data = await get(`/votacoes/${id}${qs({ iniciativa_id })}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// ── Petições ─────────────────────────────────────────────────────────────────
+
+server.tool(
+  "list_peticoes",
+  "List petitions with optional filters",
+  {
+    legislatura: z.string().optional().describe("e.g. XVII"),
+    situacao: z.string().optional().describe("e.g. Admitida, Arquivada"),
+    q: z.string().optional().describe("Search in subject"),
+    page: z.number().int().min(1).default(1).optional(),
+    limit: z.number().int().min(1).max(200).default(50).optional(),
+  },
+  async (params) => {
+    const data = await get(`/peticoes${qs(params)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "get_peticao",
+  "Get a petition with committees, rapporteurs, and documents",
+  { id: z.number().int().describe("Petition ID") },
+  async ({ id }) => {
+    const data = await get(`/peticoes/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// ── Start ────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}