# 🏭 Industrial MCP

**AI Control Plane for Operational and B2B Analytics — connecting an organizational knowledge graph, web analytics, and Cloud SQL to Claude.ai via the Model Context Protocol.**

A production [Model Context Protocol](https://modelcontextprotocol.io/) server that lets sales, marketing, and ops teams drive cross-database queries through natural language in Claude.ai instead of switching between dashboards, CLIs, and SQL clients.

The server unifies two data layers behind one agent-addressable surface:

- **Operational layer (Neo4j):** organizational structure, capability paths, knowledge-graph relationships
- **Analytics layer (Cloud SQL / Matomo):** visitor analytics, conversion metrics, content performance, B2B company intelligence

Built with Next.js on Vercel, secured via OAuth 2.1 with Auth0, and integrated with Claude.ai through the Connectors marketplace.

## 🚀 Live Deployment

- **Production:** https://industrial-mcp-delta.vercel.app
- **MCP Endpoint:** `https://industrial-mcp-delta.vercel.app/api/mcp`
- **Health Check:** https://industrial-mcp-delta.vercel.app/api/health

Connect from Claude.ai → Settings → Connectors → Add custom connector → paste the MCP endpoint.

## 🏗️ Architecture

| Layer | Technology |
|---|---|
| Runtime | Next.js 14 (App Router) on Vercel serverless |
| MCP Adapter | `@vercel/mcp-adapter` |
| Auth | OAuth 2.1 (Auth0-managed) — Bearer tokens and API keys |
| Authorization | Tool-level permission gating by user tier |
| Session / Rate Limit | Upstash Redis |
| Operational Data | Neo4j (knowledge graph) |
| Analytics Data | Google Cloud SQL (MySQL) — Matomo schema + custom |
| Language | TypeScript |

## 🔐 Authentication & Authorization

The server supports two authentication methods:

- **OAuth 2.1 Bearer tokens** — issued by Auth0 for users connecting via the Claude.ai Connectors marketplace
- **API keys** — for programmatic clients

Discovery methods (`initialize`, `tools/list`) are unauthenticated. All tool invocations (`tools/call`) require valid credentials. Each call passes through `authenticateRequest` for token validation and `hasToolPermission` for tier-based tool gating — unauthorized callers receive RFC-compliant `WWW-Authenticate` headers and JSON-RPC `-32001` / `-32003` error codes.

## 🛠️ Tools (18)

### Visitor Analytics & B2B Intelligence (Matomo)
- `get_visitor_analytics` — traffic patterns and user behavior
- `get_company_intelligence` — B2B company data from enriched session data
- `get_content_performance` — page views, bounce rates, engagement
- `get_conversion_metrics` — goal tracking and funnel analysis
- `query_matomo_database` — parameterized Matomo SQL with injection prevention

### Knowledge Graph (Neo4j)
- `query_knowledge_graph` — parameterized Cypher with injection prevention
- `find_capability_paths` — capability paths and skill networks across the org
- `get_organizational_structure` — departments and reporting hierarchies
- `get_knowledge_graph_stats` — node/relationship counts and graph health

### Cloud SQL Operations
- `explore_database` — list tables, inspect schemas, sample data
- `query_database` — custom SQL with automatic validation (SELECT-only)
- `analyze_data` — summary, trend, and distribution analysis on tables
- `get_cloud_sql_info` — system configuration and connection info
- `get_cloud_sql_status` — connection health and status

### Cross-Database
- `get_unified_dashboard_data` — combined Neo4j + MySQL metrics in a single response
- `correlate_operational_relationships` — correlate org/operational data with web analytics

### Admin
- `get_usage_analytics` — API key statistics and usage (admin-only)

### Utility
- `echo` — protocol-level testing

## 💻 Local Development

### Prerequisites

- Node.js 18+
- npm or yarn

### Setup

```bash
git clone https://github.com/intecrel/industrial-mcp.git
cd industrial-mcp
npm install
cp .env.example .env.local   # configure Auth0, Upstash, Cloud SQL, Neo4j, Matomo
npm run dev
```

### Test the MCP endpoint

```bash
curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {"roots": {"listChanged": false}},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'
```

### Test with MCP Inspector

```bash
npm install -g @modelcontextprotocol/inspector
mcp-inspector http://localhost:3000/api/mcp
```

## 🚢 Deployment

Deployed on Vercel as serverless functions:

```bash
vercel --prod
```

Required environment variables: Auth0 credentials (issuer, audience, client config), Upstash Redis URL, Cloud SQL connection string, Neo4j connection string, Matomo API token. See `.env.example` for the full list.

## 👥 Authors & History

- **Sam Durso** — Original web-based implementation
- **Muhammad Akbar Khawaja ([@akbarkhawaja](https://github.com/akbarkhawaja))** — Migration from web app to MCP server, OAuth 2.1 / Auth0 integration, knowledge-graph and Cloud SQL tooling, Claude.ai Connectors integration, current maintainer
- **intecrel** — Operating organization

The project began as a web-based operational dashboard. Once the client moved to Claude.ai as the primary user-facing surface, it was rebuilt as an MCP server with OAuth-secured tool access and the current 18-tool topology.

## 📄 License

MIT — see [LICENSE](LICENSE).

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) — protocol specification
- [Vercel MCP Adapter](https://github.com/vercel/mcp-adapter)
- [Anthropic](https://anthropic.com/) — Claude.ai and MCP development