# SecureCode MCP

Standalone MCP (Model Context Protocol) server for SecureCode AI. Provides security scanning tools to AI coding assistants — Cursor, Claude Code, Codex, Windsurf, and other compatible MCP clients — without requiring the VS Code extension.

## Install

```bash
npm install -g @securecode-ai/mcp
```

Or use directly with npx (no install needed):

```bash
npx @securecode-ai/mcp scan src/app.ts
```

## Quick Start

```bash
securecode-mcp login              # Authenticate (email + OTP)
securecode-mcp doctor             # Verify your setup works
securecode-mcp scan src/app.ts    # Scan a file from the CLI
securecode-mcp update             # Update to the latest version
securecode-mcp serve              # Start the MCP server (for AI clients)
```

## CLI Commands

```bash
securecode-mcp serve [--workspace <path>]         Start the MCP stdio server
securecode-mcp login [--api-url <url>]             Authenticate via email + OTP
securecode-mcp status                              Show current auth status
securecode-mcp logout                              Remove stored credentials
securecode-mcp scan <filePath> [--json]            Scan a single file
  [--depth <fast|deep|agent>] [--workspace <path>]
securecode-mcp doctor                              Verify setup (credentials, API, scan)
securecode-mcp update                              Update to the latest published version
securecode-mcp --help                              Show help
```

### Scan from CLI

```bash
# Agent scan (deep, AI-powered)
securecode-mcp scan src/app/api/users/route.ts

# Fast scan (no AI, free, <5s)
securecode-mcp scan src/lib/auth.ts --depth fast

# JSON output for CI
securecode-mcp scan src/app.ts --json

# Exit codes: 0 = no findings, 1 = findings found, 2 = error
```

### CI/CD Example

```yaml
# GitHub Action
- name: SecureCode scan
  run: |
    npm install -g @securecode-ai/mcp
    securecode-mcp login  # or set SECURECODE_API_TOKEN
    securecode-mcp scan src/ --json > scan-results.json
    # Exit 1 if findings found
```

## MCP client configuration

### Cursor / Windsurf

```json
{
  "mcpServers": {
    "securecode": {
      "command": "npx",
      "args": ["-y", "@securecode-ai/mcp@latest", "serve", "--workspace", "/path/to/your/project"],
      "env": {
        "SECURECODE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "securecode": {
      "command": "securecode-mcp",
      "args": ["serve", "--workspace", "/path/to/your/project"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add securecode -s user -- securecode-mcp serve --workspace /path/to/your/project
```

## Tools (17)

### Scanning

| Tool | Description | Approval |
|------|-------------|----------|
| `securecode.scan` | Scan code for vulnerabilities (AI pipeline) | No |
| `securecode.agent-scan` | Agent-mode deep scan with 20+ tools, structured proof, and sandbox verification | No |
| `securecode.agent-scan-batch` | Sequential batch scan: map + architecture scout + scan top N files one at a time | No |
| `securecode.scan-batch` | Scan multiple files in one call | No |
| `securecode.scan-secrets` | Scan for hardcoded secrets and PII (local, no AI) | No |
| `securecode.scan-dependencies` | Scan lockfiles for known vulnerabilities (OSV/NVD) | No |

### Project Analysis

| Tool | Description | Approval |
|------|-------------|----------|
| `securecode.architecture` | Run the AI architecture scout: ranked important files, trust boundaries, security controls, recommended scan order (uses AI credits, cached per depth) | No |

### Fixes & Testing

| Tool | Description | Approval |
|------|-------------|----------|
| `securecode.fix` | Generate a patch for a specific finding | Yes |
| `securecode.attack` | Endpoint red-team testing (beta) with deterministic corroboration — findings arrive confirmed/refuted with rule citations, not just "suspected" | Yes |
| `securecode.run-tests` | Run tests in sandbox for verification | Yes |

### Agent Memory (FP Learning)

| Tool | Description | Approval |
|------|-------------|----------|
| `securecode.record-false-positive` | Dismiss a finding as FP — agent learns not to report it | No |
| `securecode.get-agent-memory` | View learned false positives and known facts | No |
| `securecode.clear-agent-memory` | Clear all agent memory (or one FP by ID) | No |
| `securecode.add-known-fact` | Add a project fact for faster investigations | No |

### Finding Review

| Tool | Description | Approval |
|------|-------------|----------|
| `securecode.review-findings` | Review the finding queue for a workspace | No |
| `securecode.decide-finding` | Accept or reject a finding in the review queue | No |
| `securecode.clear-finding-reviews` | Clear all finding reviews for a workspace | No |

### How Agent Memory Works

When the agent reports a false positive, dismiss it with `record-false-positive`. The agent stores the pattern in `.securecode/agent-memory.json` and will not report similar patterns in future scans of that workspace.

```
Scan 1: Agent reports csp_bypass → You dismiss as "intentional design"
Scan 2: Agent sees the FP memory → skips similar patterns → fewer false positives
```

Memory is per-workspace, user-owned, and deletable. No cross-tenant leakage.

## Agent Scan Architecture

The agent scan (`securecode.agent-scan`) is an AI security investigator that:

1. **Maps** the project architecture (architecture scout with trust boundaries, security controls, risks)
2. **Reads** the target file and related files across the codebase
3. **Traces** data flows (taint tracking, cross-file flow with structured source→sink→hop chains)
4. **Checks** guards, endpoint policies, and configuration
5. **Verifies** threat model applicability and capability reachability
6. **Self-critiques** before reporting (selfCritique field)
7. **Gets reviewed** by an independent critique LLM
8. **Proves** findings in a sandbox (PROVEN/UNPROVEN)
9. **Runtime-verifies** HTTP findings the sandbox can't reach — with your approval, executes baseline + attack requests against your local dev server to confirm real-world impact
10. **Generates fixes** for proven findings

Agent tools (20+): `read_file`, `search_code`, `trace_flow`, `trace_flow_cross_file`, `check_guard`, `check_policy`, `get_endpoints`, `list_imports`, `list_files`, `call_graph`, `git_blame`, `git_history`, `git_diff`, `check_dependencies`, `read_config`, `find_definition`, `find_references`, `find_tests`, `run_tests`, `finish`.

The deterministic control plane enforces proof quality:
- Every finding requires source, reachability, control, threat-model, and impact evidence
- Unproven concerns become investigation notes, not findings
- Architecture risks expand across related files (callers, implementations, sinks)
- The finish gate rejects finish while proof requirements remain unsatisfied
- A non-converging finish loop escapes early: 4 consecutive rejections with the identical reason set land as `forced-incomplete` (findings salvaged, gaps recorded) instead of burning to the 45-minute wall clock

Languages: JavaScript, TypeScript, Python (partial).

## Tool Errors and Progress

**Failures say what to do, not just what broke.** A missing or expired session
returns `"Not authenticated — run securecode-mcp login and retry"`, not a bare
`Unauthorized`. Insufficient credits name the amounts and point at the top-up
page; daily limits say so; network failures say to check the connection.

The architecture scout pre-flights auth on every start, so a doomed scout never
reports `"started"`. If a background start fails anyway, the next poll returns:

```json
{ "status": "failed", "error": "Not authenticated — ...", "remedy": "Run `securecode-mcp login` and retry.", "retryable": false }
```

Retry after fixing the cause — the same call re-starts the scout automatically.
Run-pool contention (409, another scan mid-flight) is still reported as
`in-progress` with a wait hint, because waiting is the correct action there.

**Progress works in every client, no `progressToken` needed.** The
architecture tool is fast-return + poll by design (MCP clients time out long
calls), so each poll response carries live progress:

```json
{ "status": "in-progress", "progress": { "done": 12, "total": 40 }, "lastMessage": "Reading apps/server/src/http.ts (step 12)", "elapsedMs": 214000, "etaMinutes": 2 }
```

Long synchronous tools (agent-scan, fix, attack) additionally emit standard MCP
`notifications/progress` when the client sends a `progressToken` — that lights
up automatically in clients that support it.

**Cancelling works.** The server honors MCP `notifications/cancelled` — aborting
a tool call in your client fires an AbortSignal through the running scan, which
closes the run server-side (cancelled) and salvages findings found so far,
instead of orphaning a 30-45 minute scan.

## Runtime Verification

Some findings can't be proven in a sandbox — auth bypasses, runtime-dependent behavior, effects that only manifest in a live server. When an agent scan produces an HTTP-shaped finding that the sandbox couldn't prove, SecureCode can verify it against your **local dev server**:

1. The agent generates a minimal probe plan (a baseline request + attack requests) grounded in its attack library
2. You approve the probe once per scan (60-second approval window — silently skipped if you don't respond)
3. SecureCode executes the plan against `127.0.0.1:<port>` and maps the outcome to a deterministic verdict

Confirmed probes upgrade the finding to **impact-confirmed** with live response evidence.

**Safety rails:**
- Localhost only — no external traffic, ever
- Unauthenticated endpoints only; auth headers (`Authorization`, cookies, API keys) are stripped from generated plans
- Relative paths only, whitelisted methods, read-only payloads
- Max 8 requests per finding, max 3 probed findings per scan (severity-ordered)
- Plan credits are refunded if no probe can run

**Dev server discovery** (first match wins):
1. `SECURECODE_DEV_SERVER_PORT` environment variable
2. `.securecode/runtime-probe.json` in the workspace root: `{ "port": 3000 }`
3. Auto-detect across common dev ports (3000, 3001, 4000, 5173, 5174, 8000, 8080)

Disable entirely with `SECURECODE_DISABLE_RUNTIME_PROBE=1`.

> Note: probes currently fire for findings on endpoints the project map can detect (Express/Fastify-style routes). Support for other frameworks is on the roadmap.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SECURECODE_API_TOKEN` | — | API token (alternative to login) |
| `SECURECODE_API_URL` | `https://api.usesecurecode.tech` | API base URL |
| `SECURECODE_ATTACK_ENABLED` | — | Set to `1` to enable the attack tool |
| `SECURECODE_DEV_SERVER_PORT` | auto | Local dev server port for runtime verification |
| `SECURECODE_DISABLE_RUNTIME_PROBE` | — | Set to `1` to disable runtime verification probes |

## Security

- Credentials stored in OS keychain (Windows Credential Manager, macOS Keychain, Linux Secret Service) with file fallback (`~/.securecode/credentials.json`, mode 0600).
- File reads are confined to the `--workspace` root.
- Fixes are returned for review and never auto-applied.
- Agent memory is per-workspace (`.securecode/agent-memory.json`), never sent to the API.
- No telemetry.

## Development

```bash
npm install
npm run build
npm test
```

## License

MIT