Metadata-Version: 2.4
Name: nexusfeed-mcp
Version: 1.0.0
Summary: MCP server for NexusFeed — real-time B2B data (LTL fuel surcharges, ABC license compliance) for AI agents
Project-URL: Homepage, https://api.nexusfeed.dev
Project-URL: Documentation, https://api.nexusfeed.dev/docs
Project-URL: Bug Tracker, https://api.nexusfeed.dev
Author-email: NexusFeed <ops@nexusfeed.dev>
License: Commercial
Keywords: abc,ai-agents,compliance,freight,fuel-surcharge,liquor-license,ltl,mcp,nexusfeed
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp>=1.6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio==0.25.3; extra == 'dev'
Requires-Dist: pytest-mock==3.14.0; extra == 'dev'
Requires-Dist: pytest==8.3.5; extra == 'dev'
Requires-Dist: respx==0.21.1; extra == 'dev'
Requires-Dist: ruff==0.9.10; extra == 'dev'
Provides-Extra: server
Requires-Dist: apscheduler==3.11.0; extra == 'server'
Requires-Dist: beautifulsoup4==4.13.3; extra == 'server'
Requires-Dist: fastapi==0.115.12; extra == 'server'
Requires-Dist: lxml==5.3.0; extra == 'server'
Requires-Dist: playwright==1.50.0; extra == 'server'
Requires-Dist: pydantic-settings==2.7.1; extra == 'server'
Requires-Dist: pydantic==2.10.6; extra == 'server'
Requires-Dist: redis[asyncio]==5.2.1; extra == 'server'
Requires-Dist: stripe>=11.0.0; extra == 'server'
Requires-Dist: uvicorn[standard]==0.34.0; extra == 'server'
Description-Content-Type: text/markdown

# nexusfeed-mcp — MCP Server

Real-time LTL freight fuel surcharge rates and state ABC liquor license compliance records for AI agents.

Data is extracted from carrier tariff pages and state ABC portals (JS-rendered, CAPTCHAs, session state) and served as normalized, cache-backed JSON with a mandatory `_verifiability` block — extraction timestamp, confidence score, and source URL on every response.

## Tools

| Tool | Description |
|------|-------------|
| `ltl_get_fuel_surcharge` | Weekly fuel surcharge % for ODFL, Saia, Estes, ABF, R+L, TForce — includes DOE diesel price and up to 5 years of history |
| `ltl_list_carriers` | Carrier coverage metadata (SCAC codes, update schedule, extraction method) |
| `abc_search_licenses` | Search CA, TX, NY, FL license databases by trade name, owner, or address |
| `abc_lookup_license` | Point-in-time license status by state-issued license number |
| `abc_list_states` | State coverage, latency expectations, and CAPTCHA requirements |

## Workflow Prompts

| Prompt | Description |
|--------|-------------|
| `freight_audit_workflow` | Multi-step LTL invoice audit against published carrier tariffs |
| `license_compliance_check` | Compliance verification before distributor orders, insurance binding, or merchant onboarding |

## Setup

### Prerequisites

- Python 3.12+
- A NexusFeed API key (`X-API-Key`) — get one at [api.nexusfeed.dev](https://api.nexusfeed.dev)

### Install

```bash
pip install nexusfeed-mcp
```

### Configure

```bash
export MCP_API_BASE_URL=https://api.nexusfeed.dev
export MCP_API_KEY=sk_live_your_key_here
```

### Run (stdio transport)

```bash
nexusfeed-mcp
```

The server uses `stdio` transport — it reads from stdin and writes to stdout. Designed for use with Claude Desktop, Cursor, Cline, or any MCP-compatible client.

## Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "nexusfeed-mcp": {
      "command": "uvx",
      "args": ["nexusfeed-mcp"],
      "env": {
        "MCP_API_BASE_URL": "https://api.nexusfeed.dev",
        "MCP_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}
```

## Example Usage

**Fuel surcharge for invoice audit:**
```
Use ltl_get_fuel_surcharge with carriers=["ODFL"] and weeks=4 to get the last month of ODFL fuel surcharge rates.
```

**License compliance check before a transaction:**
```
Use abc_search_licenses with state="CA" and trade_name="Total Wine" to verify the license is currently ACTIVE.
```

## Verifiability

Every tool response includes:

```json
"_verifiability": {
  "source_timestamp": "2026-04-05T09:00:00Z",
  "extraction_confidence": 0.97,
  "raw_data_evidence_url": "https://odfl.com/...",
  "extraction_method": "api_mirror",
  "data_freshness_ttl_seconds": 604800
}
```

Check `extraction_confidence >= 0.90` and `source_timestamp` within `data_freshness_ttl_seconds` before using data in compliance-critical decisions.

## Troubleshooting

**401 errors on every call**
`MCP_API_KEY` is not set or is invalid. Confirm the env var is exported and matches a valid key from your NexusFeed account.

**Connection refused / could not reach API server**
`MCP_API_BASE_URL` is wrong or not set. It should be `https://api.nexusfeed.dev` (no trailing slash).

**TX TABC endpoints return 503**
The API server does not have `TWOCAPTCHA_API_KEY` configured. TX endpoints require a 2Captcha account to solve image CAPTCHAs. CA, NY, and FL have no CAPTCHA requirement.

**`extraction_confidence` below 0.90 in response**
Data quality is degraded — the extraction ran but some fields may be missing or stale. Do not use in compliance-critical decisions without verifying independently via the `raw_data_evidence_url` in the `_verifiability` block.

## License

Commercial. Contact [ops@nexusfeed.dev](mailto:ops@nexusfeed.dev) for enterprise SLA and licensing.
