Metadata-Version: 2.4
Name: compliance-os
Version: 1.0.0
Summary: Guardian — compliance copilot for visas, tax, and foreign-owned entities. MCP server with 23 tools for Claude Code / Desktop / Codex.
Author-email: Guardian <fretin13@gmail.com>
License: MIT
Project-URL: Homepage, https://guardiancompliance.app
Project-URL: Documentation, https://guardiancompliance.app/docs/install
Project-URL: Source, https://github.com/LEE-CHENYU/compliance-os
Project-URL: Issues, https://github.com/LEE-CHENYU/compliance-os/issues
Keywords: compliance,immigration,tax,h1b,stem-opt,cpt,opt,form-8843,form-1040-nr,fbar,form-5472,mcp,model-context-protocol,claude,codex,anthropic,nonresident,international-student
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Legal Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: llama-index>=0.14
Requires-Dist: llama-index-embeddings-openai>=0.5
Requires-Dist: llama-index-llms-openai>=0.6
Requires-Dist: llama-index-vector-stores-chroma>=0.5
Requires-Dist: chromadb>=1.5
Requires-Dist: openai>=2.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: psycopg[binary]>=3.2
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pymupdf>=1.24
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: python-dateutil>=2.8
Requires-Dist: bcrypt>=4.0
Requires-Dist: pyjwt>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Provides-Extra: gmail
Requires-Dist: google-auth>=2.0; extra == "gmail"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "gmail"
Requires-Dist: google-api-python-client>=2.0; extra == "gmail"
Provides-Extra: agent
Requires-Dist: mcp[cli]>=1.0; extra == "agent"
Requires-Dist: google-auth>=2.0; extra == "agent"
Requires-Dist: google-auth-oauthlib>=1.0; extra == "agent"
Requires-Dist: google-api-python-client>=2.0; extra == "agent"

# Guardian MCP Server

Connect Claude Desktop, Claude Code, or Codex to Guardian for compliance status, document processing, form filing, and Gmail integration.

## Quick Start (one command)

```bash
pip install compliance-os[agent] && guardian-mcp install
```

The installer auto-detects your apps (Claude Desktop, Claude Code, Codex) and writes the config for you. No JSON editing needed.

### Flags

```bash
guardian-mcp install              # interactive — choose apps and API
guardian-mcp install --all        # configure all detected apps (interactive API setup)
guardian-mcp install --all --local   # all apps, local dev (no token needed)
guardian-mcp uninstall            # remove Guardian from all apps
```

## What You Get

18 tools across 5 groups:

**Compliance Context** — same intelligence as the Guardian dashboard:
- `guardian_status` — findings, deadlines, key facts
- `guardian_deadlines` — upcoming deadlines sorted by urgency
- `guardian_risks` — compliance findings by severity
- `guardian_documents` — your data room inventory
- `guardian_ask` — ask Guardian's AI assistant any compliance question

**Document Processing** — runs locally on your machine (no API cost):
- `parse_document` — extract text from PDF/DOCX
- `classify_document` — identify document type (W-2, I-20, passport, etc.)
- `upload_document` — send documents to your Guardian data room
- `query_documents` — RAG search across your indexed documents

**Form Filing** — generate IRS forms locally:
- `generate_form_8843` — fill Form 8843 with filing guidance
- `run_compliance_check` — H-1B doc check, FBAR, student tax, 83(b) election
- `get_filing_guidance` — deadlines, mailing addresses, next steps

**Gmail** — compliance correspondence:
- `gmail_search` / `gmail_read` — find and read compliance-related emails
- `gmail_draft` / `gmail_send` — draft and send with PDF attachments
- `gmail_reply` — respond in-thread
- `gmail_download_attachment` — save attachments for processing

## Manual Setup (if you prefer)

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "guardian": {
      "command": "/path/to/python",
      "args": ["-m", "compliance_os.mcp_server"],
      "env": {
        "GUARDIAN_API_URL": "https://guardiancompliance.app",
        "GUARDIAN_TOKEN": "gdn_oc_YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Claude Code

Add to `~/.claude/settings.json` (global) or `.claude/mcp.json` (project):

Same JSON format as Claude Desktop.

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.guardian]
type = "stdio"
command = "/path/to/python"
args = ["-m", "compliance_os.mcp_server"]

[mcp_servers.guardian.env]
GUARDIAN_API_URL = "https://guardiancompliance.app"
GUARDIAN_TOKEN = "gdn_oc_YOUR_TOKEN_HERE"
```

## Auth

| Mode | Token needed? | How |
|------|--------------|-----|
| **Local dev** | No | Auto-generates JWT from local SQLite DB |
| **Production** | Yes | Get from Dashboard > Connect to OpenClaw |

## Gmail (optional)

```bash
python scripts/guardian_mcp_setup.py
```

Requires a one-time Google Cloud OAuth setup. See the setup script for instructions.

## Usage Examples

Once connected, just talk naturally:

- "What's my compliance status?"
- "Process these tax documents" (with file paths)
- "Generate my Form 8843 -- I'm an F-1 student from China, arrived 2022-08-15"
- "Search my Gmail for IRS notices"
- "Draft an email to my attorney with the H-1B doc check results"
- "When is my FBAR due?"

## Architecture

```
Your Machine                          Guardian API
+---------------------+               +--------------+
| Claude / Codex      |               |  Guardian     |
|                     |               |  Backend      |
|  +---------------+  |   REST API    |              |
|  | Guardian MCP   |--+--------------+> Status      |
|  | Server         |  |  (token)     |> Deadlines   |
|  |                |  |              |> Risks       |
|  | Local tools:   |  |              |> Documents   |
|  | - PDF extract  |  |              |> Chat        |
|  | - Classify     |  |              |> Upload      |
|  | - Form fill    |  |              +--------------+
|  | - Gmail OAuth  |  |
|  | - RAG query    |  |         Google API
|  |                |--+--------------> Gmail
|  +---------------+  |  (OAuth2)
+---------------------+
```

Document parsing runs locally -- your Claude/Codex handles the LLM extraction work, saving Guardian API token costs.
