Metadata-Version: 2.4
Name: dc-mcp
Version: 0.1.5
Summary: MCP client for the DoControl MCP Server
Project-URL: Homepage, https://docontrol.io
Project-URL: Repository, https://github.com/docontrol-io/dot
Author: DoControl
License: MIT
License-File: LICENSE
Keywords: ai,claude,cursor,docontrol,mcp,saas-security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=24.0
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# dc-mcp

Stdio MCP (Model Context Protocol) client for the DoControl multi-agent assistant. Connect Cursor (or any MCP-compatible client) to your DoControl tenant in under 60 seconds.

## Quick start

### 1. Install uv (one-time, if not already installed)

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Authenticate with your DoControl refresh token

```bash
uvx dc-mcp login
```

### 3. Add to `~/.cursor/mcp.json`

```jsonc
{
  "mcpServers": {
    "docontrol": {
      "command": "uvx",
      "args": ["dc-mcp"],
    },
  },
}
```

Then restart Cursor. The DoControl tools will appear in the chat sidebar.

## Get your refresh token

Log in to https://app.docontrol.io, navigate to **Settings → Integrations → MCP Token**, and click **Generate**. The token is valid for 30 days; you can regenerate it at any time.

When your token expires, simply run `uvx dc-mcp login` again with the new refresh token.

## CLI reference

| Command            | What it does                                           |
| ------------------ | ------------------------------------------------------ |
| `dc-mcp`           | Run the stdio MCP server (this is what Cursor invokes) |
| `dc-mcp login`     | Store a refresh token in your OS keychain              |
| `dc-mcp logout`    | Clear the stored refresh token                         |
| `dc-mcp whoami`    | Show your current authentication info                  |
| `dc-mcp --version` | Print the installed version                            |
| `dc-mcp --help`    | Show CLI help                                          |

## CI / headless / corporate environments

For environments where the OS keychain is unavailable (CI runners, headless Linux containers, devcontainers without Secret Service), set the refresh token via environment variable:

```bash
export DOCONTROL_REFRESH_TOKEN="..."
```

Then configure your MCP server to pass it through:

```jsonc
{
  "mcpServers": {
    "docontrol": {
      "command": "uvx",
      "args": ["dc-mcp"],
      "env": {
        "DOCONTROL_REFRESH_TOKEN": "${env:DOCONTROL_REFRESH_TOKEN}",
      },
    },
  },
}
```

The environment variable takes priority over the keychain when both are set.

## Troubleshooting

**`error: Refresh token expired or revoked`**  
Your refresh token is older than 30 days or has been revoked. Generate a new one in the DoControl webapp and run `dc-mcp login` again.

**`Network error contacting Cognito ... Check your internet connection or corporate proxy`**  
You're behind a corporate firewall. Set `HTTPS_PROXY` to your proxy URL (e.g., `export HTTPS_PROXY=http://proxy.company.com:8080`).

**`Keychain unavailable: ... On headless Linux, set DOCONTROL_REFRESH_TOKEN env var instead`**  
Your environment doesn't have a usable OS keychain (common in headless Linux or devcontainers). Use the environment variable approach from the CI section above.

**`No refresh token found`**  
Either run `dc-mcp login` to store a token in your keychain, or set the `DOCONTROL_REFRESH_TOKEN` environment variable.

**No DoControl tools appear in Cursor**  
Verify the syntax of `~/.cursor/mcp.json`, restart Cursor, then check **Cursor Settings → MCP** for connection errors. Run `dc-mcp whoami` to confirm your authentication is healthy.

**`uvx: command not found`**  
Install uv with `curl -LsSf https://astral.sh/uv/install.sh | sh` and restart your shell.

## Privacy and security

Refresh tokens are stored in your OS keychain (macOS Keychain, Windows Credential Vault, or Linux Secret Service). They never leave your machine other than to be exchanged with Cognito for short-lived access tokens.

Each request to DoControl uses a fresh access token with a one-hour time-to-live (TTL). All traffic is HTTPS to AWS-hosted endpoints. No telemetry is collected by the package.

To revoke access, run `dc-mcp logout` to clear the local token, and revoke server-side via the DoControl webapp's **Integrations** panel.

## Development & contributing

This package is part of the [docontrol-io/dot](https://github.com/docontrol-io/dot) repository. To report issues, file a GitHub issue in the main repo. For implementation details and testing, see the package source in `packages/docontrol-mcp/src/` and tests in `packages/docontrol-mcp/tests/`.

## License

MIT — see [LICENSE](LICENSE).
