fodda-mcp 1.7.0 → 1.31.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

@@ -5,9 +5,9 @@
 
   **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-io.github.piers--fawkes%2Ffodda-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.piers-fawkes/fodda)
+  [![MCP Registry](https://img.shields.io/badge/MCP_Registry-ai.fodda%2Fmcp--server-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.fodda/mcp-server)
   [![npm](https://img.shields.io/npm/v/fodda-mcp)](https://www.npmjs.com/package/fodda-mcp)
-  [![Version](https://img.shields.io/badge/version-1.4.0-green)](./CHANGELOG.md)
+  [![Version](https://img.shields.io/badge/version-1.30.0-green)](./CHANGELOG.md)
   [![License](https://img.shields.io/badge/license-Proprietary-red)](https://fodda.ai)
 
 </div>
@@ -16,16 +16,82 @@
 
 ## Quick Start
 
-### Claude Code (Streamable HTTP fallback to SSE)
+### 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"
 ```
 
-### OpenAI Frontier or Streamable HTTP Client
-Connect to the `/mcp` endpoint using HTTP `GET` to establish a stream and `POST` to execute:
-```bash
+### 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
 ```
 
@@ -50,40 +116,95 @@ 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 |
+|------|-------------|:---:|
+| `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. | ❌ |
+
+### 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 |
 |------|-------------|:---:|
-| `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 | ❌ |
+| `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.
 
-All tools require `userId` and — except `psfk_overview` — a `graphId`.
+---
 
 ### Discovery Endpoints
 
 | Endpoint | Description |
 |----------|-------------|
-| `GET /mcp/tools` | Full tool schemas, versions, and capabilities |
-| `GET /health` | Health check (`{ "status": "ok" }`) |
-| `GET /.well-known/mcp.json` | MCP server auto-discovery manifest |
+| `GET /health` | Health check (`{ "status": "ok", "version": "..." }`) |
+| `POST /mcp` | MCP endpoint — call the standard `tools/list` method on an initialized session to retrieve full tool schemas and capabilities |
 
 ---
 
 ## 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
@@ -92,11 +213,8 @@ In MCP request `_meta`:
 |----------|-------------|---------|
 | `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 | — |
-| `ALLOWED_TOOLS` | Comma-separated allowlist of Enterprise Tool scope | `search_graph,get_node,...` |
+| `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` |
 
 ---
 
@@ -124,15 +242,57 @@ PORT=8080 npm start
 
 ## MCP Registry
 
-This server is published to the [Official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.piers-fawkes/fodda`.
+This server is published to the [Official MCP Registry](https://registry.modelcontextprotocol.io) as `ai.fodda/mcp-server`.
 
 ```bash
 # Verify listing
-curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.piers-fawkes/fodda"
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=ai.fodda/mcp-server"
 ```
 
 ---
 
+## Privacy Policy
+
+Full policy: **[https://www.fodda.ai/privacy](https://www.fodda.ai/privacy)**
+
+Summary of how the Fodda MCP server handles data (the hosted policy is authoritative):
+
+- **What we collect.** *Account information* (name, email, organization) to manage your
+  account; *usage data* — API queries (query text, graph accessed, timestamps) logged for
+  billing, service improvement, and abuse prevention; and standard *technical data* (IP,
+  browser type, referral URLs). We do **not** store the full content of AI-generated
+  responses. Your API key authenticates requests and is never returned in tool output.
+- **How it's used.** To provide and improve the Services, process billing, enforce rate
+  limits and prevent abuse, communicate support/service updates, and meet legal
+  obligations. Requests are proxied to the Fodda API (`https://api.fodda.ai`) over TLS.
+- **Third-party sharing.** We do **not** sell your personal information. Data is shared
+  only with service providers (e.g. payment processors, cloud hosting) under
+  confidentiality agreements, or when required by law.
+- **AI model training.** Fodda does **not** use your queries or data to train AI models.
+  Knowledge graphs are expert-curated, not generated from user interactions.
+- **Retention.** Account information is retained while your account is active; query logs
+  are retained for billing and analytics. You may request account/data deletion via the
+  contact below.
+- **Security.** TLS-encrypted connections, API-key authentication, and secure cloud
+  infrastructure.
+- **Contact.** Privacy inquiries: **[privacy@fodda.ai](mailto:privacy@fodda.ai)**.
+
+See the [full hosted Privacy Policy](https://www.fodda.ai/privacy) (last updated
+June 16, 2026) 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;AAyJ1D,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;AA4JlB,wBAAgB,gBAAgB,CAC5B,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,cAAc,GAC7B,IAAI,CA6IN"}