fodda-mcp 1.3.2 → 1.30.0

package/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2026 Fodda / PSFK. All rights reserved.
+
+PROPRIETARY SOFTWARE LICENSE
+
+This software and associated documentation files (the "Software") are the
+proprietary and confidential property of Fodda / PSFK ("Fodda"). The Software
+is licensed, not sold.
+
+1. Grant. Subject to your compliance with these terms and the Fodda Terms of
+   Service (https://www.fodda.ai), Fodda grants you a limited, non-exclusive,
+   non-transferable, revocable license to install and run the Software solely
+   to connect to the Fodda service using a valid Fodda API key.
+
+2. Restrictions. You may not (a) copy, modify, or create derivative works of
+   the Software except as required to run it as intended; (b) sell, sublicense,
+   rent, lease, or otherwise commercially exploit the Software; (c) reverse
+   engineer or attempt to derive the source of any non-public component; or
+   (d) remove or alter any proprietary notices.
+
+3. Ownership. Fodda retains all right, title, and interest in and to the
+   Software, including all intellectual property rights.
+
+4. No Warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+5. Limitation of Liability. IN NO EVENT SHALL FODDA BE LIABLE FOR ANY CLAIM,
+   DAMAGES, OR OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE SOFTWARE
+   OR ITS USE.
+
+For licensing inquiries, contact hello@fodda.ai.

package/README.md

@@ -1,21 +1,100 @@
-# Fodda MCP Server
+<div align="center">
+  <img src="https://ucarecdn.com/6e7893d7-6b14-426b-83bc-574a3f72d6bc/foddaminilogo.png" alt="Fodda Logo" width="120"/>
+  
+  # Fodda MCP Server
 
-**Expert-curated knowledge graphs for AI agents** — PSFK Retail, Beauty, Sports and partner datasets via the Model Context Protocol.
+  **Expert-curated knowledge graphs for AI agents** — PSFK Retail, Beauty, Sports and partner datasets via the Model Context Protocol.
 
-[![MCP Registry](https://img.shields.io/badge/MCP_Registry-ai.fodda%2Fmcp--server-blue)](https://registry.modelcontextprotocol.io)
-[![Version](https://img.shields.io/badge/version-1.3.0-green)](./CHANGELOG.md)
+  [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.piers--fawkes%2Ffodda-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.piers-fawkes/fodda)
+  [![npm](https://img.shields.io/npm/v/fodda-mcp)](https://www.npmjs.com/package/fodda-mcp)
+  [![Version](https://img.shields.io/badge/version-1.29.0-green)](./CHANGELOG.md)
+  [![License](https://img.shields.io/badge/license-Proprietary-red)](https://fodda.ai)
+
+</div>
 
 ---
 
 ## Quick Start
 
-### Claude Code
+### Claude (Web — Pro, Max, Team, Enterprise)
+
+**⚡ Quick Connect:** Use this [Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Fodda&connectorUrl=https%3A%2F%2Fmcp.fodda.ai%2Fmcp%3Fapi_key%3DYOUR_API_KEY%26user_id%3DYOUR_EMAIL) quick link (replace `YOUR_API_KEY` and `YOUR_EMAIL` in the URL before pressing enter).
+
+**Manual Setup:**
+1. In Claude, go to **Settings → Connectors → Add custom connector**
+2. Enter URL: `https://mcp.fodda.ai/mcp?api_key=YOUR_API_KEY&user_id=YOUR_EMAIL`
+3. Under **Advanced settings** — leave OAuth Client ID and Secret **blank** (Fodda uses API key auth, not OAuth)
+4. Click **Add** — then start chatting with your Fodda knowledge graphs
+
+> Get your API key at [app.fodda.ai](https://app.fodda.ai) → Account → MCP Integration.  
+> Your API key starts with `sk_live_...`  
+> Use the email address associated with your Fodda account for `user_id`.
+
+### Claude Code (CLI — SSE)
 
 ```bash
 claude mcp add --transport sse fodda https://mcp.fodda.ai/sse \
   --header "Authorization: Bearer YOUR_API_KEY"
 ```
 
+### Claude Enterprise
+
+For Claude Enterprise with admin-managed connectors, your workspace admin can register the Fodda MCP server using the same Streamable HTTP endpoint (`https://mcp.fodda.ai/mcp`) via the Admin Console. See [Enterprise MCP Setup](./Enterprise_MCP_Setup.md) for full details.
+
+### OpenAI (Responses API — Recommended)
+
+Use OpenAI's native MCP support — no function definitions needed:
+
+```python
+from openai import OpenAI
+client = OpenAI()
+
+resp = client.responses.create(
+    model="gpt-5",
+    tools=[{
+        "type": "mcp",
+        "server_label": "fodda",
+        "server_description": "Expert-curated knowledge graphs for retail, beauty, sports trends and earnings intelligence.",
+        "server_url": "https://mcp.fodda.ai/mcp",
+        "authorization": "Bearer YOUR_API_KEY",
+        "require_approval": "never",
+    }],
+    input="What are the top emerging retail trends?",
+)
+print(resp.output_text)
+```
+
+```javascript
+import OpenAI from "openai";
+const client = new OpenAI();
+
+const resp = await client.responses.create({
+  model: "gpt-5",
+  tools: [{
+    type: "mcp",
+    server_label: "fodda",
+    server_description: "Expert-curated knowledge graphs for retail, beauty, sports trends and earnings intelligence.",
+    server_url: "https://mcp.fodda.ai/mcp",
+    authorization: "Bearer YOUR_API_KEY",
+    require_approval: "never",
+  }],
+  input: "What are the top emerging retail trends?",
+});
+console.log(resp.output_text);
+```
+
+> **Tip:** To reduce latency with 30+ tools, use `allowed_tools` to filter:
+> `"allowed_tools": ["search_graph", "search_statistics", "brand_tracker"]`
+
+> **Legacy:** If you're using `chat.completions.create()` with function calling, define a custom function that calls the Fodda REST API. See [fodda.ai/connect](https://app.fodda.ai) for details.
+
+### Generic Streamable HTTP Client
+
+Connect to the `/mcp` endpoint using HTTP `POST` (Streamable HTTP) with `Authorization: Bearer YOUR_API_KEY`:
+```
+https://mcp.fodda.ai/mcp
+```
+
 ### Gemini CLI
 
 ```json
@@ -37,16 +116,63 @@ Connect to `https://mcp.fodda.ai/sse` with an `Authorization: Bearer YOUR_API_KE
 
 ## Available Tools
 
+The Fodda MCP server exposes a rich suite of 30 tools to search, analyze, brainstorm, and visualize trends, expert-curated knowledge graphs, and corporate documents.
+
+### Discovery & Search
+| Tool | Description | Deterministic |
+|------|-------------|:---:|
+| `list_graphs` | Discover available knowledge graphs, metadata, and routing instructions. | ✅ |
+| `search_graph` | Hybrid keyword + semantic search across curated graphs for trend clusters and evidence. | ❌ |
+| `search_statistics` | Search for specific quantitative metrics, indicators, and numeric data points. | ❌ |
+| `search_insights` | Search expert quotes, qualitative signals, and professional interpretations. | ❌ |
+| `get_label_values` | Discover valid values for a node label or category. | ✅ |
+
+### Traversal & Graph Operations
+| Tool | Description | Deterministic |
+|------|-------------|:---:|
+| `get_neighbors` | Traverse from seed nodes to discover related concept nodes and links. | ✅ |
+| `get_node` | Retrieve detailed metadata, properties, and attributes for a single node by ID. | ✅ |
+| `get_evidence` | Retrieve source signals, articles, citations, and provenance for a trend or node. | ✅ |
+| `discover_adjacent_trends` | Find semantically similar trends to a given trend node. | ✅ |
+
+### Intelligence Domains
 | Tool | Description | Deterministic |
 |------|-------------|:---:|
-| `search_graph` | Hybrid keyword + semantic search on a knowledge graph | ❌ |
-| `get_neighbors` | Traverse from seed nodes to discover related concepts | ✅ |
-| `get_evidence` | Source signals, articles, and provenance for a node | ✅ |
-| `get_node` | Retrieve metadata for a single node by ID | ✅ |
-| `get_label_values` | Discover valid values for a node label/category | ✅ |
-| `psfk_overview` | Structured macro overview across industries and sectors | ❌ |
+| `get_domain_intelligence` | Search all PSFK curated domain graphs (retail, beauty, sports, fashion, consumer electronics, F&B) in parallel. | ❌ |
+| `get_expert_intelligence` | Query specialist industry graphs built by leading strategists and experts. | ❌ |
+| `get_report_intelligence` | Search institutional report insights from DHL, PwC, Delta, and other partners. | ❌ |
 
-All tools require `userId` and — except `psfk_overview` — a `graphId`.
+### Earnings & Corporate Insights
+| Tool | Description | Deterministic |
+|------|-------------|:---:|
+| `get_earnings_intelligence` | Query management commentary, business guidance, and Q&A from company earnings calls. | ❌ |
+| `get_earnings_divergence` | Detect deflections, gaps, and divergence between analyst concerns and executive responses in earnings calls. | ❌ |
+
+### Brand & Ideation
+| Tool | Description | Deterministic |
+|------|-------------|:---:|
+| `brand_tracker` | Compile a comprehensive Brand Intelligence Profile across all knowledge graphs. | ❌ |
+| `brainstorm_topic` | Graph-powered brainstorm map discovering unexpected connections and adjacent territories. | ❌ |
+
+### Deep Research & Execution Agents
+| Tool | Description | Deterministic |
+|------|-------------|:---:|
+| `deep_research_topic` | Launch an autonomous research session combining graphs with live web search. | ❌ |
+| `check_research_status` | Check progress or retrieve the final narrative report of a deep research job. | ✅ |
+| `get_supplemental_context` | Fetch macro context from up to 10 institutional data sources in a single query. | ❌ |
+| `check_supplemental_status` | Retrieve output from a supplemental context job. | ✅ |
+
+### Synthetic Analyst & Visualization
+| Tool | Description | Deterministic |
+|------|-------------|:---:|
+| `list_analysts` | List available Synthetic Analyst expert personas. | ✅ |
+| `consult_analyst` | Engage a Synthetic Analyst persona to synthesize answers with specialized voice. | ❌ |
+| `generate_visual` | Generate branded SVG data visualizations (Cultural Shifts, Competitive Compass, Innovation Pathway, etc.). | ❌ |
+> **Note on Dynamic Partner Skills:** When partner skills (such as Paralogy or Igloo) are enabled for a user's account, additional specialized tools (e.g. `paralogy_analyze_trends`, ideation tools) are dynamically registered on the MCP server and made available automatically.
+>
+> **Note on System Utilities:** The server also registers several helper and account management utilities (e.g., `get_my_account`, `toggle_graph_preference`, `update_user_profile`, `manage_scheduled_reports`, `send_feedback`) to allow the AI assistant to query subscription status, manage scheduled briefings, or save personalization settings directly.
+
+---
 
 ### Discovery Endpoints
 
@@ -60,29 +186,36 @@ All tools require `userId` and — except `psfk_overview` — a `graphId`.
 
 ## Authentication
 
+**Preferred — HTTP header (used by the directory connection and all header-capable clients).**
 Pass your Fodda API key as a Bearer token:
 
 ```
-Authorization: Bearer fk_live_...
+Authorization: Bearer sk_live_...
 ```
 
+The server also accepts the key via an `X-API-Key: sk_live_...` header.
+
 In MCP request `_meta`:
 ```json
-{ "_meta": { "authorization": "Bearer fk_live_..." } }
+{ "_meta": { "authorization": "Bearer sk_live_..." } }
 ```
 
+**Fallback — URL query parameter.** Some clients (e.g. the Claude.ai web *custom
+connector* UI) cannot set custom request headers. For those, the key may be passed as
+`?api_key=...`. This is provided only for compatibility; prefer header-based auth
+wherever the client supports it, since URLs are more likely to be logged by
+intermediaries. The server never returns your API key in tool output.
+
 ---
 
 ## Configuration
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `PORT` | SSE server port (omit for stdio mode) | — |
+| `PORT` | HTTP server port (omit for stdio mode) | — |
 | `FODDA_API_URL` | Upstream API base URL | `https://api.fodda.ai` |
-| `FODDA_MCP_SECRET` | HMAC signing secret | — |
+| `FODDA_MCP_SECRET` | HMAC signing secret for API requests | — |
 | `NODE_ENV` | Environment (`development` / `production`) | `production` |
-| `INTERNAL_TEST_KEYS` | Comma-separated keys for simulation mode | — |
-| `RATE_LIMIT_RPM` | Requests per minute per API key | `60` |
 
 ---
 
@@ -110,15 +243,54 @@ PORT=8080 npm start
 
 ## MCP Registry
 
-This server is published to the [Official MCP Registry](https://registry.modelcontextprotocol.io) as `ai.fodda/mcp-server`.
+This server is published to the [Official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.piers-fawkes/fodda`.
 
 ```bash
 # Verify listing
-curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.fodda/mcp-server"
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.piers-fawkes/fodda"
 ```
 
 ---
 
+## Privacy Policy
+
+Full policy: **[https://www.fodda.ai/privacy](https://www.fodda.ai/privacy)**
+
+Summary of how the Fodda MCP server handles data:
+
+- **What we collect.** Your Fodda API key (for authentication and billing) and the
+  `user_id`/email associated with your Fodda account. Tool calls you make (queries,
+  parameters, and the graphs/skills accessed) are processed to return results and may
+  be logged for reliability, abuse prevention, and usage metering.
+- **How it's used and stored.** Requests are proxied to the Fodda API
+  (`https://api.fodda.ai`) over HTTPS. Session and account state is stored in Fodda's
+  managed infrastructure. Your API key is transmitted only to authenticate your
+  requests and is never returned in tool output.
+- **Third-party sharing.** We do not sell your data. Query content may be processed by
+  sub-processors strictly to deliver the service (e.g. model inference and
+  transactional email providers). Partner "skills," when enabled by you, process only
+  the queries you direct to them.
+- **Retention.** Account and usage records are retained while your account is active
+  and for the period required for billing, security, and legal obligations. See the
+  hosted policy for specifics.
+- **Contact.** Privacy questions: **[hello@fodda.ai](mailto:hello@fodda.ai)**.
+
+See the [full hosted Privacy Policy](https://www.fodda.ai/privacy) for the complete,
+authoritative terms.
+
+---
+
+## Support
+
+- **Email:** [hello@fodda.ai](mailto:hello@fodda.ai)
+- **Account & API keys:** [app.fodda.ai](https://app.fodda.ai) → Account → MCP Integration
+- **Documentation:** [fodda.ai](https://www.fodda.ai)
+
+To report a security issue, email **[hello@fodda.ai](mailto:hello@fodda.ai)** with
+"SECURITY" in the subject line.
+
+---
+
 ## License
 
 Proprietary — [fodda.ai](https://www.fodda.ai)

package/dist/a2aHandler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A2A (Agent-to-Agent) Protocol Handler
+ *
+ * Implements JSON-RPC 2.0 over HTTP per the A2A v1.0 specification.
+ * MVP: Supports `message/send` only — receives a natural language task,
+ * routes it through Fodda's existing tool handlers, and returns
+ * structured results as A2A Task artifacts.
+ *
+ * A2A vs MCP:
+ *  - MCP: client agent calls Fodda tools directly (tool-level granularity)
+ *  - A2A: client agent delegates a *task* in natural language; Fodda decides
+ *         which tools to use and returns the synthesized result
+ *
+ * Spec: https://a2a-protocol.org/latest/specification/
+ */
+import type { Express } from 'express';
+type FoddaRequestFn = (method: 'GET' | 'POST' | 'PATCH', path: string, apiKey: string, userId: string, body?: any) => Promise<any>;
+export declare function registerA2ARoute(app: Express, foddaRequest: FoddaRequestFn): void;
+export {};
+//# sourceMappingURL=a2aHandler.d.ts.map

package/dist/a2aHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2aHandler.d.ts","sourceRoot":"","sources":["../src/a2aHandler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAsF1D,KAAK,cAAc,GAAG,CAClB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,EAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,GAAG,KACT,OAAO,CAAC,GAAG,CAAC,CAAC;AAgIlB,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,cAAc,GAC7B,IAAI,CAwIN"}

package/dist/a2aHandler.js

@@ -0,0 +1,247 @@
+/**
+ * A2A (Agent-to-Agent) Protocol Handler
+ *
+ * Implements JSON-RPC 2.0 over HTTP per the A2A v1.0 specification.
+ * MVP: Supports `message/send` only — receives a natural language task,
+ * routes it through Fodda's existing tool handlers, and returns
+ * structured results as A2A Task artifacts.
+ *
+ * A2A vs MCP:
+ *  - MCP: client agent calls Fodda tools directly (tool-level granularity)
+ *  - A2A: client agent delegates a *task* in natural language; Fodda decides
+ *         which tools to use and returns the synthesized result
+ *
+ * Spec: https://a2a-protocol.org/latest/specification/
+ */
+import crypto from 'crypto';
+function classifyIntent(text) {
+    const lower = text.toLowerCase();
+    // Brand-focused queries
+    const brandMatch = lower.match(/(?:what is |what's |tell me about |brand (?:intelligence|profile|tracker) (?:for |on )?|track )([a-z][a-z0-9 &'.-]{1,30}?)(?:\s+(?:doing|strategy|innovation|positioning|trends?))?$/i);
+    if (brandMatch && brandMatch[1]) {
+        return { tool: 'brand_tracker', params: { brand_name: brandMatch[1].trim() } };
+    }
+    // Explicit brand mentions with "what is X doing" pattern
+    const doingMatch = text.match(/what (?:is|are) ([A-Z][A-Za-z0-9 &'.-]{1,30}?) doing/);
+    if (doingMatch && doingMatch[1]) {
+        return { tool: 'brand_tracker', params: { brand_name: doingMatch[1].trim() } };
+    }
+    // Deep research triggers
+    if (lower.includes('deep research') || lower.includes('comprehensive report') ||
+        lower.includes('write me a report') || lower.includes('detailed analysis')) {
+        return { tool: 'deep_research', params: { query: text, depth: 'light' } };
+    }
+    // Earnings triggers
+    if (lower.includes('earnings') || lower.includes('q1 ') || lower.includes('q2 ') ||
+        lower.includes('q3 ') || lower.includes('q4 ') || lower.match(/what (?:are|did) .+ (?:companies|brands) say/)) {
+        return { tool: 'earnings', params: { query: text } };
+    }
+    // Default: search_graph (the most general tool)
+    return { tool: 'search_graph', params: { query: text } };
+}
+async function executeQuery(route, apiKey, userId, foddaRequest) {
+    switch (route.tool) {
+        case 'search_graph': {
+            // Search ALL graphs (no graphId = all-graph parallel search)
+            const body = {
+                query: route.params.query,
+                limit: 10,
+                use_semantic: true,
+                include_evidence: true,
+            };
+            const result = await foddaRequest('POST', '/v1/graphs/search', apiKey, userId, body);
+            const rows = result?.rows || [];
+            if (rows.length === 0) {
+                return { text: `No trends found for: "${route.params.query}". Fodda's knowledge graphs may not have coverage on this specific topic.`, data: result };
+            }
+            // Build a concise markdown summary
+            const lines = [];
+            lines.push(`## Fodda Trend Intelligence: ${route.params.query}\n`);
+            lines.push(`_${rows.length} trends found across Fodda's expert-curated knowledge graphs._\n`);
+            for (const row of rows.slice(0, 8)) {
+                const score = row.signal_score ? ` (signal: ${row.signal_score})` : '';
+                const lifecycle = row.trendLifecycle ? ` · ${row.trendLifecycle}` : '';
+                const graph = row.graphName ? ` — _${row.graphName}_` : '';
+                lines.push(`### ${row.title || row.trendName}${score}${lifecycle}`);
+                if (row.summary || row.description) {
+                    lines.push((row.summary || row.description).substring(0, 300));
+                }
+                if (row.evidence && row.evidence.length > 0) {
+                    lines.push('');
+                    for (const ev of row.evidence.slice(0, 3)) {
+                        const link = ev.sourceUrl ? ` — [source](${ev.sourceUrl})` : '';
+                        lines.push(`- ${(ev.title || ev.snippet || '').substring(0, 150)}${link}`);
+                    }
+                }
+                lines.push(`${graph}\n`);
+            }
+            return { text: lines.join('\n'), data: result };
+        }
+        case 'brand_tracker': {
+            const body = { brand_name: route.params.brand_name };
+            const result = await foddaRequest('POST', '/v1/brands/intelligence', apiKey, userId, body);
+            const lines = [];
+            lines.push(`## Brand Intelligence: ${route.params.brand_name}\n`);
+            if (result?.trend_footprint) {
+                lines.push(`_Appears in ${result.trend_footprint.length} trends across ${result.cross_graph_presence?.length || 0} knowledge graphs._\n`);
+                for (const t of (result.trend_footprint || []).slice(0, 6)) {
+                    const score = t.signal_score ? ` (signal: ${t.signal_score})` : '';
+                    lines.push(`- **${t.trend_name}**${score} · ${t.lifecycle || 'unknown'} — ${t.graph_name || ''}`);
+                }
+            }
+            if (result?.competitive_context?.co_occurring?.length > 0) {
+                lines.push(`\n### Competitive Context`);
+                for (const c of result.competitive_context.co_occurring.slice(0, 5)) {
+                    lines.push(`- ${c.brand} (${c.pressure_type})`);
+                }
+            }
+            return { text: lines.join('\n') || JSON.stringify(result, null, 2), data: result };
+        }
+        case 'earnings': {
+            const body = { query: route.params.query, limit: 10 };
+            const result = await foddaRequest('POST', '/v1/earnings/search', apiKey, userId, body);
+            return {
+                text: result?.summary || JSON.stringify(result, null, 2),
+                data: result,
+            };
+        }
+        case 'deep_research': {
+            // For A2A MVP, we do a synchronous search (not the async deep_research job)
+            // because A2A registries expect a timely response for health probes.
+            const body = {
+                query: route.params.query,
+                limit: 15,
+                use_semantic: true,
+                include_evidence: true,
+            };
+            const result = await foddaRequest('POST', '/v1/graphs/search', apiKey, userId, body);
+            const rows = result?.rows || [];
+            const lines = [];
+            lines.push(`## Research Summary: ${route.params.query}\n`);
+            lines.push(`_${rows.length} trends analyzed from Fodda's knowledge graph network._\n`);
+            for (const row of rows.slice(0, 10)) {
+                const score = row.signal_score ? ` (signal: ${row.signal_score})` : '';
+                lines.push(`### ${row.title || row.trendName}${score}`);
+                if (row.summary || row.description) {
+                    lines.push((row.summary || row.description).substring(0, 400));
+                }
+                lines.push('');
+            }
+            return { text: lines.join('\n'), data: result };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON-RPC helpers
+// ---------------------------------------------------------------------------
+function jsonRpcSuccess(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function jsonRpcError(id, code, message, data) {
+    return { jsonrpc: '2.0', id, error: { code, message, ...(data ? { data } : {}) } };
+}
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+export function registerA2ARoute(app, foddaRequest) {
+    app.post('/a2a', async (req, res) => {
+        // ── Parse & validate JSON-RPC envelope ──
+        const body = req.body;
+        if (!body || body.jsonrpc !== '2.0') {
+            return res.status(400).json(jsonRpcError(body?.id ?? null, -32600, 'Invalid Request: missing jsonrpc 2.0 field'));
+        }
+        const requestId = body.id ?? null;
+        // ── Method dispatch ──
+        switch (body.method) {
+            case 'message/send':
+                break; // handled below
+            // Stubs for future methods — return Method Not Found
+            case 'message/stream':
+            case 'tasks/get':
+            case 'tasks/cancel':
+            case 'tasks/list':
+                return res.json(jsonRpcError(requestId, -32601, `Method not found: ${body.method}. Only message/send is supported in this version.`));
+            default:
+                return res.json(jsonRpcError(requestId, -32601, `Method not found: ${body.method}`));
+        }
+        // ── Extract user text from message parts ──
+        const message = body.params?.message;
+        if (!message?.parts?.length) {
+            return res.json(jsonRpcError(requestId, -32602, 'Invalid params: message.parts is required and must be non-empty'));
+        }
+        const textPart = message.parts.find(p => p.kind === 'text' && p.text);
+        if (!textPart?.text) {
+            return res.json(jsonRpcError(requestId, -32602, 'Invalid params: no text part found in message'));
+        }
+        const queryText = textPart.text;
+        // ── Authentication ──
+        // Accept: Authorization: Bearer <key>, X-API-Key header, or api_key query param
+        const apiKey = (req.headers['authorization']?.toString().replace(/^Bearer\s+/i, ''))
+            || req.headers['x-api-key']
+            || req.query.api_key
+            || '';
+        const userId = req.headers['x-user-id']
+            || req.query.user_id
+            || 'a2a-agent';
+        // For unauthenticated requests (health probes), return a minimal valid response
+        if (!apiKey) {
+            const taskId = `task-${crypto.randomUUID().slice(0, 8)}`;
+            const contextId = `ctx-${crypto.randomUUID().slice(0, 8)}`;
+            return res.json(jsonRpcSuccess(requestId, {
+                id: taskId,
+                contextId,
+                status: { state: 'completed' },
+                artifacts: [{
+                        name: 'health_check',
+                        parts: [{
+                                kind: 'text',
+                                text: 'Fodda A2A endpoint is operational. Provide an API key via Authorization: Bearer <key> for full access to trend intelligence. Get a key at https://app.fodda.ai',
+                            }],
+                    }],
+            }));
+        }
+        // ── Route and execute ──
+        try {
+            const route = classifyIntent(queryText);
+            console.error(`[a2a] message/send: "${queryText.substring(0, 80)}" → ${route.tool}`);
+            const result = await executeQuery(route, apiKey, userId, foddaRequest);
+            const taskId = `task-${crypto.randomUUID().slice(0, 8)}`;
+            const contextId = `ctx-${crypto.randomUUID().slice(0, 8)}`;
+            // Build artifacts — always include markdown text, optionally raw JSON
+            const artifacts = [
+                {
+                    name: 'research_result',
+                    description: `Fodda intelligence for: ${queryText.substring(0, 100)}`,
+                    parts: [{ kind: 'text', text: result.text }],
+                },
+            ];
+            // Include raw data as a structured artifact if the client accepts JSON
+            const acceptedOutputs = body.params?.configuration?.acceptedOutputModes || [];
+            if (acceptedOutputs.includes('application/json') && result.data) {
+                artifacts.push({
+                    name: 'raw_data',
+                    description: 'Structured JSON data from Fodda knowledge graphs',
+                    parts: [{ kind: 'data', data: result.data, mimeType: 'application/json' }],
+                });
+            }
+            return res.json(jsonRpcSuccess(requestId, {
+                id: taskId,
+                contextId,
+                status: { state: 'completed' },
+                artifacts,
+            }));
+        }
+        catch (err) {
+            const statusCode = err.response?.status;
+            const errMsg = err.response?.data?.error?.message || err.message || 'Internal error';
+            console.error(`[a2a] Error: ${errMsg}`);
+            // Map known error types to appropriate JSON-RPC error codes
+            if (statusCode === 401 || statusCode === 403) {
+                return res.json(jsonRpcError(requestId, -32001, `Unauthorized: ${errMsg}`));
+            }
+            return res.json(jsonRpcError(requestId, -32603, `Fodda query failed: ${errMsg}`));
+        }
+    });
+    console.error('[a2a] A2A endpoint registered at POST /a2a');
+}
+//# sourceMappingURL=a2aHandler.js.map

package/dist/a2aHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2aHandler.js","sourceRoot":"","sources":["../src/a2aHandler.ts"],"names":[],"mappings":"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"}

package/dist/agents/fodda-researcher/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Fodda Research Agent — System Instruction Builder
+ *
+ * Loads the 5 skill files and assembles a system instruction for the
+ * Gemini Interactions API. This is the "agent" — a skill-injected system
+ * prompt that tells Gemini how to conduct Fodda-style research.
+ *
+ * Usage:
+ *   import { buildResearcherInstruction } from './agents/fodda-researcher/index.js';
+ *   const systemInstruction = buildResearcherInstruction(query, graphContext);
+ */
+/**
+ * Context about pre-fetched Fodda graph results, injected into the
+ * system instruction so the agent can reference existing knowledge.
+ */
+export interface GraphContext {
+    /** Pre-fetched trends from Fodda graphs, stringified JSON */
+    graphResults?: string;
+    /** Which graphs were searched */
+    graphsSearched?: string[];
+    /** Total trends found across all graphs */
+    totalTrends?: number;
+    /** Total evidence pieces collected */
+    totalEvidence?: number;
+    /** Optional specific graph to focus on (undefined = search all) */
+    focusGraphId?: string | undefined;
+}
+/**
+ * Build the complete system instruction for the Fodda Research Agent.
+ *
+ * Concatenates all 5 skill files with a mission preamble and any
+ * graph context that was pre-fetched from Fodda's knowledge graphs.
+ */
+export declare function buildResearcherInstruction(query: string, context?: GraphContext): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/fodda-researcher/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/fodda-researcher/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,YAAY,GACvB,MAAM,CA8CR"}