@perenia/mcp 0.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @perenia/mcp
+
+MCP server for the [Perenia Partner API](https://api.perenia.ai/v1/docs) —
+search and analyze ~3.5M French companies from Claude, Cursor, or any MCP
+client. Runs locally over stdio; every call goes to `https://api.perenia.ai`
+with your API key, so your plan's rate limits and quotas apply as usual.
+
+## Setup
+
+You need a Perenia Partner API key (`pk_live_…`).
+
+**Claude Code**
+
+```bash
+claude mcp add perenia --env PERENIA_API_KEY=pk_live_… -- npx -y @perenia/mcp
+```
+
+**Claude Desktop / other clients** (`claude_desktop_config.json` or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "perenia": {
+      "command": "npx",
+      "args": ["-y", "@perenia/mcp"],
+      "env": { "PERENIA_API_KEY": "pk_live_…" }
+    }
+  }
+}
+```
+
+Optional: `PERENIA_API_URL` overrides the API base URL (for local development
+against a dev instance).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_companies` | Text + filtered search (location, NAF activity, size, financials, financial-score grade, decision-maker age, geo radius). Compact summaries, paginated. |
+| `get_company` | Full profile by SIREN, including multi-year financial history. |
+| `get_company_officers` | Officer roster (names and roles — no personal data). |
+| `get_network_neighbours` | Companies sharing an officer network (holdings, sister companies). |
+| `list_facet_values` | Valid values + company counts for a categorical field, optionally scoped by filters — use it to discover filter values or get distributions. |
+
+Data refreshes daily. Errors carry the API's error code; a `429` includes the
+`Retry-After` hint (per-minute rate limit or daily quota — see your contract).
+
+## Development (this repo)
+
+```bash
+npm -w @perenia/mcp test         # in-memory MCP client ↔ server against an API stub
+npm -w @perenia/mcp run build    # emit dist/
+PERENIA_API_KEY=… npm -w @perenia/mcp run dev
+```
+
+Publishing: `npm publish -w @perenia/mcp` (runs `build` via prepublishOnly).

package/dist/client.js

@@ -0,0 +1,50 @@
+/** Thin HTTP client for the Perenia Partner API. All MCP tools go through
+ * this — the server never talks to anything but the public /v1 surface, so
+ * per-key auth, rate limits, quotas, and metering apply exactly as they do
+ * for any other API consumer. */
+export class PereniaApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    constructor(status, code, message, retryAfterSeconds) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'PereniaApiError';
+    }
+}
+export class ApiClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async get(path, query) {
+        const qs = query && Object.keys(query).length ? `?${new URLSearchParams(query)}` : '';
+        return this.request('GET', `${path}${qs}`);
+    }
+    async post(path, body) {
+        return this.request('POST', path, body);
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.opts.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.opts.apiKey}`,
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const payload = await res.json().catch(() => undefined);
+        if (!res.ok) {
+            const err = payload?.error;
+            const code = err?.code ?? `http_${res.status}`;
+            let message = err?.message ?? `request failed with status ${res.status}`;
+            if (res.status === 401)
+                message = `${message} — check PERENIA_API_KEY`;
+            const retryAfter = res.headers.get('retry-after');
+            throw new PereniaApiError(res.status, code, message, retryAfter ? Number(retryAfter) : undefined);
+        }
+        return payload;
+    }
+}

package/dist/filters.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+/**
+ * Curated, flat, agent-friendly filter parameters, mapped onto the API's
+ * FilterState wire format. Deliberately a subset: the dimensions an agent can
+ * use well, with describe() strings doing the prompting.
+ */
+export const searchFiltersShape = {
+    query: z.string().optional().describe('Full-text query over company names and activity descriptions'),
+    regions: z.array(z.string()).optional().describe("Region names, e.g. 'Occitanie' — values via list_facet_values('region_name')"),
+    departments: z.array(z.string()).optional().describe("Department codes, e.g. '31'"),
+    naf_sections: z.array(z.string()).optional().describe("NAF section letters, e.g. 'F' (construction)"),
+    naf_codes: z.array(z.string()).optional().describe("NAF/APE activity codes, e.g. '62.01Z' — values via list_facet_values('main_activity_code')"),
+    legal_type_codes: z.array(z.string()).optional().describe("INSEE legal-form codes, e.g. '5710' (SAS)"),
+    company_categories: z.array(z.string()).optional().describe('PME, ETI, or GE'),
+    employment_size_bins: z.array(z.string()).optional().describe("INSEE workforce bin codes — values via list_facet_values('employment_size_bin_code')"),
+    filing_status: z.array(z.enum(['disclosed', 'partial', 'none'])).optional().describe('Financial-filing disclosure status'),
+    in_collective_proceeding: z.boolean().optional().describe('true = only companies in an open procédure collective, false = exclude them'),
+    creation_year_min: z.number().int().optional(),
+    creation_year_max: z.number().int().optional(),
+    decision_maker_age_min: z.number().int().optional().describe('Min age (years) of the oldest primary decision-maker — succession signal'),
+    decision_maker_age_max: z.number().int().optional(),
+    turnover_min: z.number().optional().describe('Latest-filing turnover, EUR'),
+    turnover_max: z.number().optional(),
+    net_profit_min: z.number().optional(),
+    net_profit_max: z.number().optional(),
+    financial_score_min: z.number().optional().describe('Financial score percentile 0–100'),
+    financial_score_max: z.number().optional(),
+    financial_score_grades: z.array(z.enum(['A', 'B', 'C', 'D', 'E'])).optional(),
+    lat: z.number().optional().describe('With lng and radius_km: geographic radius filter'),
+    lng: z.number().optional(),
+    radius_km: z.number().optional(),
+    sort: z
+        .enum(['creation_date_desc', 'creation_date_asc', 'dm_age_desc', 'score_desc', 'score_asc'])
+        .optional()
+        .describe('Default: relevance'),
+};
+const filtersSchema = z.object(searchFiltersShape);
+/** Map the flat tool params to the API's FilterState keys. */
+export function toFilterState(f) {
+    const out = {};
+    if (f.query)
+        out.query = f.query;
+    if (f.regions?.length)
+        out.regions = f.regions;
+    if (f.departments?.length)
+        out.departments = f.departments;
+    if (f.naf_sections?.length)
+        out.nafSections = f.naf_sections;
+    if (f.naf_codes?.length)
+        out.nafCodes = f.naf_codes;
+    if (f.legal_type_codes?.length)
+        out.legalTypeCodes = f.legal_type_codes;
+    if (f.company_categories?.length)
+        out.companyCategories = f.company_categories;
+    if (f.employment_size_bins?.length)
+        out.employmentSizeBins = f.employment_size_bins;
+    if (f.filing_status?.length)
+        out.financialFilingStatus = f.filing_status;
+    if (f.in_collective_proceeding !== undefined)
+        out.collectiveProceeding = f.in_collective_proceeding ? 'in' : 'not';
+    if (f.creation_year_min != null)
+        out.creationYearMin = f.creation_year_min;
+    if (f.creation_year_max != null)
+        out.creationYearMax = f.creation_year_max;
+    if (f.decision_maker_age_min != null)
+        out.decisionMakerAgeMin = f.decision_maker_age_min;
+    if (f.decision_maker_age_max != null)
+        out.decisionMakerAgeMax = f.decision_maker_age_max;
+    if (f.turnover_min != null)
+        out.turnoverMin = f.turnover_min;
+    if (f.turnover_max != null)
+        out.turnoverMax = f.turnover_max;
+    if (f.net_profit_min != null)
+        out.netProfitMin = f.net_profit_min;
+    if (f.net_profit_max != null)
+        out.netProfitMax = f.net_profit_max;
+    if (f.financial_score_min != null)
+        out.financialScoreMin = f.financial_score_min;
+    if (f.financial_score_max != null)
+        out.financialScoreMax = f.financial_score_max;
+    if (f.financial_score_grades?.length)
+        out.financialScoreGrades = f.financial_score_grades;
+    if (f.lat != null && f.lng != null && f.radius_km != null) {
+        out.geoCenter = { lat: f.lat, lng: f.lng };
+        out.geoRadiusKm = f.radius_km;
+    }
+    if (f.sort)
+        out.sort = f.sort;
+    return out;
+}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ApiClient } from './client.js';
+import { registerTools } from './tools.js';
+// stdio transport: stdout is the protocol channel — diagnostics go to stderr.
+const apiKey = process.env.PERENIA_API_KEY;
+if (!apiKey) {
+    console.error('PERENIA_API_KEY is required (your pk_live_… Perenia Partner API key).');
+    process.exit(1);
+}
+const baseUrl = (process.env.PERENIA_API_URL ?? 'https://api.perenia.ai').replace(/\/$/, '');
+const server = new McpServer({ name: 'perenia', version: '0.1.0' });
+registerTools(server, new ApiClient({ baseUrl, apiKey }));
+await server.connect(new StdioServerTransport());
+console.error(`perenia-mcp ready (${baseUrl})`);

package/dist/tools.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { PereniaApiError } from './client.js';
+import { searchFiltersShape, toFilterState } from './filters.js';
+const sirenParam = z.string().regex(/^\d{9}$/).describe('9-digit SIREN identifier');
+const FACET_FIELDS = [
+    'region_name',
+    'department_code',
+    'naf_section',
+    'main_activity_code',
+    'legal_type_code',
+    'company_category',
+    'employment_size_bin_code',
+    'independence_proxy',
+    'network_coverage',
+    'financial_filing_status',
+    'last_financial_score_grade',
+    'has_open_collective_proceeding',
+];
+/** Compact per-hit shape for search-style results: enough to reason and rank
+ * with, small enough that a 25-hit page doesn't flood the agent's context.
+ * Full detail is one get_company call away. */
+function trimSummary(c) {
+    return {
+        siren: c.siren,
+        name: c.name,
+        city: c.city_name,
+        region: c.region_name,
+        naf_code: c.main_activity_code,
+        activity: c.main_activity_label,
+        category: c.company_category,
+        employees: c.employment_size_bin_label,
+        creation_year: c.creation_year,
+        turnover: c.last_turnover,
+        score_grade: c.last_financial_score_grade,
+        max_decision_maker_age: c.max_primary_decision_maker_age_years,
+        in_collective_proceeding: c.has_open_collective_proceeding,
+        one_liner: c.one_liner,
+        url: c.url,
+    };
+}
+function ok(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 1) }] };
+}
+async function guarded(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof PereniaApiError) {
+            const retry = err.retryAfterSeconds != null ? ` (retry after ${err.retryAfterSeconds}s)` : '';
+            return { content: [{ type: 'text', text: `Perenia API error ${err.status} ${err.code}: ${err.message}${retry}` }], isError: true };
+        }
+        throw err;
+    }
+}
+export function registerTools(server, api) {
+    server.registerTool('search_companies', {
+        description: 'Search ~3.5M French companies by text query and/or filters (location, activity, size, financials, decision-maker age, financial-score grade). Returns compact summaries — use get_company for full detail. Data refreshes daily.',
+        inputSchema: {
+            ...searchFiltersShape,
+            page: z.number().int().min(1).max(100).optional().describe('Default 1'),
+            per_page: z.number().int().min(1).max(50).optional().describe('Default 10'),
+        },
+    }, (args) => guarded(async () => {
+        const { page, per_page, ...filters } = args;
+        const res = (await api.post('/v1/companies/search', {
+            ...toFilterState(filters),
+            page: page ?? 1,
+            perPage: per_page ?? 10,
+        }));
+        return ok({ total: res.total, page: res.page, per_page: res.per_page, companies: res.data.map(trimSummary) });
+    }));
+    server.registerTool('get_company', {
+        description: 'Full profile of one company by SIREN: identity, location, activity descriptions, network counts, financial score, and multi-year financial history.',
+        inputSchema: { siren: sirenParam },
+    }, ({ siren }) => guarded(async () => ok(await api.get(`/v1/companies/${siren}`))));
+    server.registerTool('get_company_officers', {
+        description: 'Officer roster (directors, managers) of one company by SIREN. Names and roles only — no personal data.',
+        inputSchema: { siren: sirenParam },
+    }, ({ siren }) => guarded(async () => ok(await api.get(`/v1/companies/${siren}/officers`))));
+    server.registerTool('get_network_neighbours', {
+        description: 'Companies sharing an officer network with the given SIREN (up to 50) — subsidiaries, sister companies, holdings.',
+        inputSchema: { siren: sirenParam },
+    }, ({ siren }) => guarded(async () => {
+        const res = (await api.get(`/v1/companies/${siren}/neighbours`));
+        return ok({ neighbours: res.data.map(trimSummary) });
+    }));
+    server.registerTool('list_facet_values', {
+        description: 'All values (with company counts) of one categorical field, optionally scoped by the same filters as search_companies. Use it to discover valid filter values or get distributions.',
+        inputSchema: {
+            field: z.enum(FACET_FIELDS),
+            ...searchFiltersShape,
+        },
+    }, (args) => guarded(async () => {
+        const { field, ...filters } = args;
+        const state = toFilterState(filters);
+        const query = Object.keys(state).length ? { filters: JSON.stringify(state) } : undefined;
+        return ok(await api.get(`/v1/facets/${field}`, query));
+    }));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@perenia/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Perenia Partner API — search and analyze French companies from any MCP client",
+  "type": "module",
+  "license": "UNLICENSED",
+  "bin": {
+    "perenia-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.8"
+  }
+}