open-primitive-mcp 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# Open Primitive Protocol (OPP)
+
+**The data layer of the agent internet.**
+
+OPP defines how data providers make their data agent-consumable, verifiable, and discoverable. Three components: provider manifest, response envelope, query interface.
+
+## The Problem
+
+Agents get data naked. No provenance. No freshness guarantee. No confidence score. No way to verify the source. The agent internet is missing its data envelope.
+
+## The Protocol
+
+| Component | What it does |
+|-----------|-------------|
+| **Manifest** (`/.well-known/opp.json`) | Declares what data a provider serves, how fresh it is, how to verify it |
+| **Response Envelope** | Every response carries domain, source, freshness, confidence, citation, Ed25519 signature |
+| **Query Interface** | Standardized HTTP GET endpoints with predictable parameters |
+
+## Conformance Levels
+
+- **Level 1 (Basic):** Manifest + envelope with domain/source/freshness
+- **Level 2 (Cited):** Level 1 + confidence scores + citations
+- **Level 3 (Verified):** Level 2 + Ed25519 cryptographic proof
+
+## Reference Implementation
+
+Live at [api.openprimitive.com](https://api.openprimitive.com). 16 US federal data domains across 11 agencies. Level 3 compliant — every response is signed.
+
+```bash
+curl https://api.openprimitive.com/v1/drugs?name=aspirin
+# Returns OPP envelope with proof.type: "DataIntegrityProof"
+```
+
+## Quick Start
+
+**Use data from an OPP provider:**
+```javascript
+const res = await fetch('https://api.openprimitive.com/v1/drugs?name=aspirin');
+const data = await res.json();
+console.log(data.citations.statement);
+// "According to FDA FAERS, aspirin has 601,477 reported adverse events"
+```
+
+**Implement OPP for your own data:**
+```javascript
+// 1. Create /.well-known/opp.json (see spec)
+// 2. Wrap responses in the OPP envelope
+// 3. Optionally sign with Ed25519
+```
+
+## Specification
+
+Full spec: [openprimitive.com/protocol.html](https://openprimitive.com/protocol.html)
+
+Detailed spec: [api.openprimitive.com/spec.html](https://api.openprimitive.com/spec.html)
+
+## SDK
+
+- `sdk/opp-client.js` — Client library for consuming OPP providers
+- `sdk/opp-provider.js` — Helper for implementing OPP
+- `sdk/opp-validator.js` — Validate OPP conformance
+
+## MCP Server
+
+13 tools for Claude, Cursor, and MCP-compatible agents:
+
+```bash
+npx open-primitive-mcp
+```
+
+## Links
+
+- [Protocol Spec](https://openprimitive.com/protocol.html)
+- [API Reference](https://api.openprimitive.com)
+- [Manifesto](https://openprimitive.com/manifesto.html)
+- [OpenAPI Spec](https://api.openprimitive.com/openapi.json)
+- [OPP Manifest](https://api.openprimitive.com/.well-known/opp.json)
+
+## License
+
+MIT

package/mcp.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+
+const flights = require('./sources/flights');
+const cars = require('./sources/cars');
+const food = require('./sources/food');
+const water = require('./sources/water');
+const drugs = require('./sources/drugs');
+const hospitals = require('./sources/hospitals');
+const health = require('./sources/health');
+const nutrition = require('./sources/nutrition');
+const jobs = require('./sources/jobs');
+const demographics = require('./sources/demographics');
+const products = require('./sources/products');
+const sec = require('./sources/sec');
+const safety = require('./sources/safety');
+
+const server = new McpServer({
+  name: 'open-primitive',
+  version: '1.0.0',
+});
+
+// ─── FLIGHTS ───
+server.registerTool('get-flights', {
+  title: 'Get Flight Status',
+  description: 'Get live delay and weather data for 8 major US airlines. Source: FAA NAS + Open-Meteo.',
+  inputSchema: z.object({
+    airline: z.string().optional().describe('IATA code (DL, UA, AA, WN, AS, B6, G4, F9). Omit for all airlines.'),
+  }),
+}, async ({ airline }) => {
+  const data = airline ? await flights.getAirline(airline) : await flights.getAirlines();
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── CARS ───
+server.registerTool('get-car-safety', {
+  title: 'Get Car Safety',
+  description: 'Get NHTSA crash safety ratings and recalls for a vehicle. Source: NHTSA.',
+  inputSchema: z.object({
+    year: z.string().describe('Model year (e.g. "2024")'),
+    make: z.string().describe('Manufacturer (e.g. "Toyota")'),
+    model: z.string().describe('Model name (e.g. "Camry")'),
+  }),
+}, async ({ year, make, model }) => {
+  const data = await cars.getSafety(year, make, model);
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── FOOD ───
+server.registerTool('get-food-recalls', {
+  title: 'Get Food Recalls',
+  description: 'Get active FDA food recalls or search by product/brand. Source: FDA Enforcement.',
+  inputSchema: z.object({
+    query: z.string().optional().describe('Search term (product or brand). Omit for recent recalls.'),
+  }),
+}, async ({ query }) => {
+  const data = query ? await food.search(query) : await food.getRecent();
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── WATER ───
+server.registerTool('get-water-safety', {
+  title: 'Get Water Safety',
+  description: 'Get drinking water system data and violations. Source: EPA SDWIS.',
+  inputSchema: z.object({
+    zip: z.string().optional().describe('5-digit ZIP code to find water systems'),
+    pwsid: z.string().optional().describe('Public Water System ID for detailed violations'),
+  }),
+}, async ({ zip, pwsid }) => {
+  const data = pwsid ? await water.getSystem(pwsid) : await water.searchByZip(zip || '');
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── DRUGS ───
+server.registerTool('get-drug-safety', {
+  title: 'Get Drug Safety',
+  description: 'Get FDA adverse event reports, top reactions, and label warnings for a drug. Source: FDA FAERS.',
+  inputSchema: z.object({
+    name: z.string().describe('Drug name (brand or generic, e.g. "ibuprofen")'),
+  }),
+}, async ({ name }) => {
+  const data = await drugs.getDrug(name);
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── HOSPITALS ───
+server.registerTool('get-hospital-quality', {
+  title: 'Get Hospital Quality',
+  description: 'Search hospitals or get detailed quality ratings. Source: CMS Care Compare.',
+  inputSchema: z.object({
+    query: z.string().optional().describe('Hospital name or ZIP code to search'),
+    providerId: z.string().optional().describe('CMS Provider ID for detailed quality data'),
+  }),
+}, async ({ query, providerId }) => {
+  const data = providerId ? await hospitals.getHospital(providerId) : await hospitals.searchHospitals(query || '');
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── HEALTH ───
+server.registerTool('get-health-evidence', {
+  title: 'Get Health Evidence',
+  description: 'Search PubMed for research evidence on supplements or health claims. Source: PubMed/MEDLINE.',
+  inputSchema: z.object({
+    query: z.string().describe('Supplement name or health claim (e.g. "vitamin d", "turmeric inflammation")'),
+  }),
+}, async ({ query }) => {
+  const data = await health.searchHealth(query);
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── NUTRITION ───
+server.registerTool('get-nutrition', {
+  title: 'Get Nutrition Data',
+  description: 'Search USDA FoodData Central for nutrition facts or get details by FDC ID. Source: USDA.',
+  inputSchema: z.object({
+    query: z.string().optional().describe('Food search term (e.g. "banana", "cheddar cheese"). Omit if using fdcId.'),
+    fdcId: z.string().optional().describe('FDC ID for a specific food item. Omit if using query.'),
+  }),
+}, async ({ query, fdcId }) => {
+  const data = fdcId ? await nutrition.getFood(fdcId) : await nutrition.searchFood(query || '');
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── JOBS ───
+server.registerTool('get-jobs', {
+  title: 'Get Jobs Data',
+  description: 'Get unemployment rate or other BLS time series data. Source: Bureau of Labor Statistics.',
+  inputSchema: z.object({
+    seriesId: z.string().optional().describe('BLS series ID (e.g. "LNS14000000" for unemployment rate). Omit for default unemployment data.'),
+  }),
+}, async ({ seriesId }) => {
+  const data = seriesId ? await jobs.getSeriesData(seriesId) : await jobs.getUnemployment();
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── DEMOGRAPHICS ───
+server.registerTool('get-demographics', {
+  title: 'Get Demographics',
+  description: 'Get Census demographics for a ZIP code: population, income, poverty, education, housing. Source: US Census ACS.',
+  inputSchema: z.object({
+    zip: z.string().describe('5-digit ZIP code'),
+  }),
+}, async ({ zip }) => {
+  const data = await demographics.getByZip(zip);
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── PRODUCT RECALLS ───
+server.registerTool('get-product-recalls', {
+  title: 'Get Product Recalls',
+  description: 'Get recent CPSC consumer product recalls or search by keyword. Source: SaferProducts.gov.',
+  inputSchema: z.object({
+    query: z.string().optional().describe('Search term (product type or brand). Omit for recent recalls.'),
+  }),
+}, async ({ query }) => {
+  const data = query ? await products.search(query) : await products.getRecent();
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── SEC FILINGS ───
+server.registerTool('get-sec-filings', {
+  title: 'Get SEC Filings',
+  description: 'Search SEC EDGAR for company filings or get structured financial facts by CIK. Source: SEC EDGAR.',
+  inputSchema: z.object({
+    query: z.string().optional().describe('Company name to search (e.g. "Apple"). Omit if using cik.'),
+    cik: z.string().optional().describe('SEC CIK number for detailed company facts. Omit if using query.'),
+  }),
+}, async ({ query, cik }) => {
+  const data = cik ? await sec.getCompanyFacts(cik) : await sec.searchCompany(query || '');
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// ─── SAFETY PROFILE ───
+server.registerTool('get-safety-profile', {
+  title: 'Get Safety Profile',
+  description: 'Get a cross-domain safety composite for a ZIP code combining water quality and hospital ratings. Source: EPA + CMS.',
+  inputSchema: z.object({
+    zip: z.string().describe('5-digit ZIP code'),
+  }),
+}, async ({ zip }) => {
+  const data = await safety.getSafetyProfile(zip);
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+});
+
+// Start
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "open-primitive-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for 13 federal data domains — flights, cars, food, water, drugs, hospitals, health, nutrition, jobs, demographics, products, SEC, safety",
+  "main": "mcp.js",
+  "bin": {
+    "open-primitive-mcp": "./mcp.js"
+  },
+  "files": ["mcp.js", "sources/", "package.json"],
+  "keywords": ["mcp", "model-context-protocol", "federal-data", "government", "ai-agents", "open-primitive"],
+  "author": "David Hamilton <davehamiltonj@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/writesdavid/open-primitive-api"
+  },
+  "dependencies": {
+    "node-fetch": "^2.7.0",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.24.0"
+  }
+}

package/sources/alerts.js

@@ -0,0 +1,190 @@
+const { Redis } = require('@upstash/redis');
+const food = require('./food');
+const products = require('./products');
+
+const ALERT_KEY = 'alerts:feed';
+const SNAPSHOT_KEY = 'alerts:snapshot';
+const MAX_ALERTS = 50;
+
+let redis = null;
+
+function getRedis() {
+  if (!redis && process.env.UPSTASH_REDIS_REST_URL) {
+    redis = new Redis({
+      url: process.env.UPSTASH_REDIS_REST_URL,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN,
+    });
+  }
+  return redis;
+}
+
+// ─── ALERT RULES ───
+// Each rule: { domain, match(item) => alert | null }
+
+const FOOD_RULES = {
+  domain: 'food',
+  extract(recalls) {
+    return recalls
+      .filter(r => r.classification === 'Class I')
+      .map(r => ({
+        domain: 'food',
+        event: 'class_i_recall',
+        severity: 'critical',
+        title: `Class I Recall: ${(r.firm || 'Unknown firm').slice(0, 80)}`,
+        summary: (r.reason || '').slice(0, 300),
+        data: {
+          product: r.product,
+          firm: r.firm,
+          recallNumber: r.recallNumber,
+          date: r.date,
+          distribution: r.distribution,
+        },
+        endpoint: '/v1/food',
+        timestamp: new Date().toISOString(),
+      }));
+  },
+  fingerprint(item) {
+    return `food:${item.data.recallNumber || item.title}`;
+  },
+};
+
+const PRODUCTS_RULES = {
+  domain: 'products',
+  extract(recalls) {
+    const childKeywords = /child|infant|baby|toddler|kid|crib|stroller|toy|pacifier|nursery/i;
+    return recalls
+      .filter(r => {
+        const text = `${r.title} ${r.description} ${(r.products || []).map(p => p.name).join(' ')}`;
+        return childKeywords.test(text);
+      })
+      .map(r => ({
+        domain: 'products',
+        event: 'children_product_recall',
+        severity: 'critical',
+        title: `Children's Product Recall: ${(r.title || '').slice(0, 80)}`,
+        summary: (r.description || '').slice(0, 300),
+        data: {
+          recallId: r.recallId,
+          products: r.products,
+          hazards: r.hazards,
+          manufacturers: r.manufacturers,
+          recallDate: r.recallDate,
+          url: r.url,
+        },
+        endpoint: '/v1/products',
+        timestamp: new Date().toISOString(),
+      }));
+  },
+  fingerprint(item) {
+    return `products:${item.data.recallId || item.title}`;
+  },
+};
+
+// ─── CORE ───
+
+async function getSnapshot() {
+  const r = getRedis();
+  if (!r) return {};
+  const raw = await r.get(SNAPSHOT_KEY);
+  if (!raw) return {};
+  return typeof raw === 'string' ? JSON.parse(raw) : raw;
+}
+
+async function saveSnapshot(snapshot) {
+  const r = getRedis();
+  if (!r) return;
+  await r.set(SNAPSHOT_KEY, JSON.stringify(snapshot));
+}
+
+async function pushAlerts(newAlerts) {
+  const r = getRedis();
+  if (!r) return;
+  const raw = await r.get(ALERT_KEY);
+  let existing = [];
+  if (raw) {
+    existing = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  }
+  const merged = [...newAlerts, ...existing].slice(0, MAX_ALERTS);
+  await r.set(ALERT_KEY, JSON.stringify(merged));
+}
+
+async function checkForAlerts() {
+  const snapshot = await getSnapshot();
+  const newAlerts = [];
+
+  // Food: Class I recalls
+  try {
+    const foodData = await food.getRecent();
+    if (foodData.recalls && !foodData.error) {
+      const candidates = FOOD_RULES.extract(foodData.recalls);
+      for (const alert of candidates) {
+        const fp = FOOD_RULES.fingerprint(alert);
+        if (!snapshot[fp]) {
+          newAlerts.push(alert);
+          snapshot[fp] = Date.now();
+        }
+      }
+    }
+  } catch (err) {
+    console.error('Alert check failed for food:', err.message);
+  }
+
+  // Products: children's recalls
+  try {
+    const productsData = await products.getRecent();
+    if (productsData.recalls && !productsData.error) {
+      const candidates = PRODUCTS_RULES.extract(productsData.recalls);
+      for (const alert of candidates) {
+        const fp = PRODUCTS_RULES.fingerprint(alert);
+        if (!snapshot[fp]) {
+          newAlerts.push(alert);
+          snapshot[fp] = Date.now();
+        }
+      }
+    }
+  } catch (err) {
+    console.error('Alert check failed for products:', err.message);
+  }
+
+  // Prune snapshot entries older than 90 days
+  const cutoff = Date.now() - 90 * 24 * 60 * 60 * 1000;
+  for (const key of Object.keys(snapshot)) {
+    if (snapshot[key] < cutoff) delete snapshot[key];
+  }
+
+  if (newAlerts.length > 0) {
+    await pushAlerts(newAlerts);
+  }
+  await saveSnapshot(snapshot);
+
+  return newAlerts;
+}
+
+async function getAlertFeed() {
+  const r = getRedis();
+
+  // No Redis: run a live check and return what we find
+  if (!r) {
+    const live = await checkForAlerts();
+    return {
+      alerts: live.slice(0, MAX_ALERTS),
+      count: live.length,
+      lastUpdated: new Date().toISOString(),
+      note: 'Live check — no persistent store configured',
+    };
+  }
+
+  const raw = await r.get(ALERT_KEY);
+  let alerts = [];
+  if (raw) {
+    alerts = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  }
+
+  return {
+    alerts,
+    count: alerts.length,
+    lastUpdated: alerts.length > 0 ? alerts[0].timestamp : null,
+  };
+}
+
+module.exports = { checkForAlerts, getAlertFeed };