@perenia/mcp 0.2.0 → 0.3.0

package/README.md

@@ -37,7 +37,13 @@ against a dev instance).
 | 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 — or, with `columns`, rows holding exactly the requested columns (same ids as the web table's templates and CSV export). |
-| `list_columns` | The column catalogue for `search_companies` `columns`, grouped, with each column's kind and fields. No quota cost. |
+| `get_companies` | Batch lookup of up to 100 SIRENs in one call, in the order given, as summaries or `columns` rows; reports the SIRENs not found. |
+| `open_in_perenia` | Turns the same filters as `search_companies` into the URL of that search in the web app — the link to hand to a person. |
+| `list_columns` | The column catalogue for `columns`, grouped, with each column's kind and fields. No quota cost. |
+| `get_usage` | Today's quota for your key (used / limit / remaining / reset) and the per-minute rate limit. Every other tool result already ends with the same `quota` figures. |
+
+Every result carries `perenia_url` per company (the company page in the app).
+`PERENIA_APP_URL` overrides the app origin those links use.
 | `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). |

package/dist/client.js

@@ -16,6 +16,8 @@ export class PereniaApiError extends Error {
 }
 export class ApiClient {
     opts;
+    /** Last X-Quota-* headers seen; null until an authenticated call returns. */
+    lastQuota = null;
     constructor(opts) {
         this.opts = opts;
     }
@@ -35,6 +37,7 @@ export class ApiClient {
             },
             body: body !== undefined ? JSON.stringify(body) : undefined,
         });
+        this.captureQuota(res.headers);
         const payload = await res.json().catch(() => undefined);
         if (!res.ok) {
             const err = payload?.error;
@@ -47,4 +50,11 @@ export class ApiClient {
         }
         return payload;
     }
+    captureQuota(headers) {
+        const used = Number(headers.get('x-quota-used'));
+        const limit = Number(headers.get('x-quota-limit'));
+        if (!headers.has('x-quota-used') || !Number.isFinite(used) || !Number.isFinite(limit))
+            return;
+        this.lastQuota = { used, limit, remaining: Math.max(0, limit - used) };
+    }
 }

package/dist/index.js

@@ -10,7 +10,8 @@ if (!apiKey) {
     process.exit(1);
 }
 const baseUrl = (process.env.PERENIA_API_URL ?? 'https://api.perenia.ai').replace(/\/$/, '');
-const server = new McpServer({ name: 'perenia', version: '0.2.0' });
-registerTools(server, new ApiClient({ baseUrl, apiKey }));
+const appUrl = (process.env.PERENIA_APP_URL ?? 'https://app.perenia.ai').replace(/\/$/, '');
+const server = new McpServer({ name: 'perenia', version: '0.3.0' });
+registerTools(server, new ApiClient({ baseUrl, apiKey }), { appUrl });
 await server.connect(new StdioServerTransport());
 console.error(`perenia-mcp ready (${baseUrl})`);

package/dist/tools.js

@@ -16,11 +16,32 @@ const FACET_FIELDS = [
     '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 {
+const columnsParam = z
+    .array(z.string())
+    .min(1)
+    .max(40)
+    .optional()
+    .describe('Ordered column ids from list_columns, e.g. ["company", "turnover", "netProfit", "founded"]. When set, results are rows keyed by column id (siren first; a code column also carries <id>_label) instead of compact summaries — pick the columns you need for a table or a comparison.');
+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, opts) {
+    const appUrl = opts.appUrl.replace(/\/$/, '');
+    const companyUrl = (siren) => `${appUrl}/company/${String(siren)}`;
+    /** 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; `perenia_url` opens the company
+     * in the app for a person. */
+    const trimSummary = (c) => ({
         siren: c.siren,
         name: c.name,
         city: c.city_name,
@@ -36,34 +57,26 @@ function trimSummary(c) {
         in_collective_proceeding: c.has_open_collective_proceeding,
         one_liner: c.one_liner,
         url: c.url,
+        perenia_url: companyUrl(c.siren),
+    });
+    const withUrl = (row) => ({ ...row, perenia_url: companyUrl(row.siren) });
+    /** Every metered result ends with the daily quota as the API reported it
+     * on that very response, so the agent can pace itself without a call. */
+    const ok = (data) => {
+        const payload = api.lastQuota ? { ...data, quota: api.lastQuota } : data;
+        return { content: [{ type: 'text', text: JSON.stringify(payload, null, 1) }] };
+    };
+    const presentSearch = (res) => {
+        const paging = { total: res.total, page: res.page, per_page: res.per_page };
+        if (res.rows)
+            return { ...paging, columns: res.columns, rows: res.rows.map(withUrl) };
+        return { ...paging, companies: (res.data ?? []).map(trimSummary) };
     };
-}
-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, or — with `columns` — one row per company holding exactly the requested columns (ids from list_columns). Use get_company for full detail. Data refreshes daily.',
+        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, or — with `columns` — one row per company holding exactly the requested columns (ids from list_columns). Each result carries `perenia_url` (the company in the app); use open_in_perenia to hand the whole search to a person. Use get_company for full detail. Data refreshes daily.',
         inputSchema: {
             ...searchFiltersShape,
-            columns: z
-                .array(z.string())
-                .min(1)
-                .max(40)
-                .optional()
-                .describe('Ordered column ids from list_columns, e.g. ["company", "turnover", "netProfit", "founded"]. When set, results are rows keyed by column id (siren first; a code column also carries <id>_label) instead of compact summaries — pick the columns you need for a table or a comparison.'),
+            columns: columnsParam,
             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'),
         },
@@ -75,29 +88,42 @@ export function registerTools(server, api) {
             page: page ?? 1,
             perPage: per_page ?? 10,
         }));
-        const paging = { total: res.total, page: res.page, per_page: res.per_page };
-        if (res.rows)
-            return ok({ ...paging, columns: res.columns, rows: res.rows });
-        return ok({ ...paging, companies: (res.data ?? []).map(trimSummary) });
+        return ok(presentSearch(res));
     }));
-    server.registerTool('list_columns', {
-        description: 'The column catalogue accepted by search_companies `columns`, grouped (profile, location, people, financials, score, network) with each column\'s value kind and the fields it reads. Cheap: no quota cost.',
-        inputSchema: {},
-    }, () => guarded(async () => {
-        const res = (await api.get('/v1/columns'));
-        const groups = {};
-        for (const { group, ...column } of res.columns)
-            (groups[group] ??= []).push(column);
-        return ok({ groups });
+    server.registerTool('get_companies', {
+        description: 'Batch lookup of up to 100 companies by SIREN in one call (one request against the quota). Returns them in the order given, as compact summaries or — with `columns` — as rows, plus the SIRENs that were not found.',
+        inputSchema: {
+            sirens: z.array(sirenParam).min(1).max(100),
+            columns: columnsParam,
+        },
+    }, ({ sirens, columns }) => guarded(async () => {
+        const wanted = [...new Set(sirens)];
+        const res = (await api.post('/v1/companies/search', {
+            companyIds: wanted,
+            ...(columns ? { columns } : {}),
+            page: 1,
+            perPage: wanted.length,
+        }));
+        const found = presentSearch(res);
+        const items = (found.rows ?? found.companies ?? []);
+        const bySiren = new Map(items.map((item) => [String(item.siren), item]));
+        const ordered = wanted.flatMap((s) => (bySiren.has(s) ? [bySiren.get(s)] : []));
+        const missing = wanted.filter((s) => !bySiren.has(s));
+        return ok(found.rows
+            ? { found: ordered.length, missing, columns: found.columns, rows: ordered }
+            : { found: ordered.length, missing, companies: ordered });
     }));
     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.',
+        description: 'Full profile of one company by SIREN: identity, location, activity descriptions, network counts, financial score, and multi-year financial history. Includes `perenia_url` (the company page in the app).',
         inputSchema: { siren: sirenParam },
-    }, ({ siren }) => guarded(async () => ok(await api.get(`/v1/companies/${siren}`))));
+    }, ({ siren }) => guarded(async () => {
+        const detail = (await api.get(`/v1/companies/${siren}`));
+        return ok(withUrl(detail));
+    }));
     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`))));
+    }, ({ 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 },
@@ -115,6 +141,27 @@ export function registerTools(server, api) {
         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));
+        return ok((await api.get(`/v1/facets/${field}`, query)));
+    }));
+    server.registerTool('list_columns', {
+        description: 'The column catalogue accepted by search_companies / get_companies `columns`, grouped (profile, location, people, financials, score, network) with each column\'s value kind and the fields it reads. Cheap: no quota cost.',
+        inputSchema: {},
+    }, () => guarded(async () => {
+        const res = (await api.get('/v1/columns'));
+        const groups = {};
+        for (const { group, ...column } of res.columns)
+            (groups[group] ??= []).push(column);
+        return ok({ groups });
     }));
+    server.registerTool('open_in_perenia', {
+        description: 'Hand a search to a person: the same filters as search_companies become the URL of that search in the Perenia web app (live results, facets, export, lists). Returns the link — give it to the user. A geographic radius (lat/lng) has no URL form and is dropped.',
+        inputSchema: { ...searchFiltersShape },
+    }, (args) => guarded(async () => {
+        const res = (await api.post('/v1/links/search', toFilterState(args)));
+        return ok({ url: res.url });
+    }));
+    server.registerTool('get_usage', {
+        description: "This API key's daily quota: requests used today (UTC), the limit, what remains and when it resets, plus the per-minute rate limit. Every other tool result already ends with the same `quota` figures, so call this only when you have not made a call yet.",
+        inputSchema: {},
+    }, () => guarded(async () => ok((await api.get('/v1/usage')))));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perenia/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for the Perenia Partner API — search and analyze French companies from any MCP client",
   "type": "module",
   "license": "UNLICENSED",