Metadata-Version: 2.4
Name: dealgo-mcp
Version: 0.1.0
Summary: MCP server for DeAlgo CSC — runtime decision firewall for AI agents. Drop into Claude Desktop, Claude Code, or Cursor and your agent must consult csc_check before acting.
Author: DeAlgo Systems
License: Apache-2.0
Project-URL: Homepage, https://api.dealgo.io
Project-URL: Documentation, https://api.dealgo.io/docs
Project-URL: Repository, https://github.com/dealgo-systems/dealgo-mcp-server
Project-URL: Issues, https://github.com/dealgo-systems/dealgo-mcp-server/issues
Keywords: mcp,ai,agent,governance,safety,claude,decision,firewall
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"

# DeAlgo MCP Server

Runtime decision firewall for AI agents. Exposes the **CSC** engine (via the
`dealgo-portal` control layer) as a Model Context Protocol server so any
MCP-aware client — Claude Desktop, Claude Code, Cursor, custom agents — can
consult CSC before executing risky actions.

```
Claude / agent
      ↓
MCP tool: csc_check(...)
      ↓
dealgo-portal /api/csc/check  (Bearer dealgo_sk_live_…)
      ↓
CSC engine: reality · policy · throttle gates
      ↓
{ decision, action, reason, v2_bias, latency_ms }
```

## Tools

### `csc_check(feed, risk?, volatility?, confidence?, symbol?, source?, intent?, v2_aware=True)`

Primary tool. Score one signal/action against CSC. Returns

```json
{ "decision": "APPROVE" | "DELAY" | "DENY",
  "action":   "EXECUTE" | "WAIT" | "REJECT",
  "reason":   "...",
  "v2_bias":  -0.018,
  "stimulus_id": "stim_…",
  "latency_ms": 41 }
```

Proceed only on `APPROVE`. On `DELAY`, retry with backoff. On `DENY`, do
not retry — surface the `reason` to the user.

### `check_action(intent, action, actor_id, domain, environment, metadata)`

Backwards-compat shim. Maps the legacy governance payload onto `csc_check`
so existing demos and Claude Desktop configs keep working. Prefer
`csc_check` directly in new code.

## Resource

`governance://decisions/recent` — last 20 decisions logged for the
configured API key. Lets agents introspect their own history.

## Setup (recommended — published package)

1. **Install:**
   ```bash
   pip install dealgo-mcp
   ```
2. **Get a sandbox key** from your portal at <https://api.dealgo.io/keys>
   (or `https://api.dealgo.io/quickstart` for a one-click reveal). Use a
   `dealgo_sk_test_…` key for a no-meter sandbox, `dealgo_sk_live_…` for prod.
3. **Wire into Claude Desktop.** Merge this into the config:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   ```json
   {
     "mcpServers": {
       "dealgo-csc": {
         "command": "dealgo-mcp",
         "env": {
           "DEALGO_API_KEY": "dealgo_sk_test_…",
           "DEALGO_API_URL": "https://api.dealgo.io"
         }
       }
     }
   }
   ```
4. **Restart Claude Desktop.** Then ask Claude:

   > "Use `csc_check` before doing anything risky."

   Every risky action will now consult `/v1/decide` and surface the verdict.

## Setup (local dev — from source)

```bash
git clone https://github.com/dealgo-systems/dealgo-mcp-server
cd dealgo-mcp-server
pip install -e .            # editable install — picks up changes immediately
```

Then point Claude Desktop config to the editable install (`"command": "dealgo-mcp"`
still works after `pip install -e .` — entry point is registered system-wide).

## Smoke test

```bash
DEALGO_API_KEY=dealgo_sk_test_... python smoke_test.py
```

Exercises all three CSC gates (reality, policy, throttle), the
backwards-compat shim, and the recent-decisions resource. Pass = CSC
governance is live over MCP.

## Configuration

| Env var          | Default                    | Required |
|------------------|----------------------------|----------|
| `DEALGO_API_KEY` | (none)                     | yes      |
| `DEALGO_API_URL` | `https://api.dealgo.io`    | no       |

Now Claude can call CSC before executing actions.
