Metadata-Version: 2.4
Name: mcpshield-agent
Version: 0.1.0
Summary: MCPShield Agent - AI Agent Security Scanner for MCP servers
Author-email: David Cooper <hello@mcpshield.app>
License-Expression: MIT
Project-URL: Homepage, https://mcpshield.app
Project-URL: Repository, https://github.com/RunTimeAdmin/MCPShield
Project-URL: Issues, https://github.com/RunTimeAdmin/MCPShield/issues
Project-URL: Documentation, https://mcpshield.app/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: psutil>=5.9.0

# MCPShield Agent

AI Agent Security Scanner - Discovers MCP servers on your system and reports them to MCPShield for security analysis.

## Installation

```bash
# From source
pip install -e .

# Or from PyPI (when published)
pip install mcpshield-agent
```

## Quick Start

```bash
# 1. Configure with your API key (get from dashboard)
mcpshield configure --api-key mcp_sk_your_key_here

# 2. Scan for MCP servers
mcpshield scan

# 3. Check status
mcpshield status
```

## Commands

| Command | Description |
|---------|-------------|
| `mcpshield configure --api-key KEY` | Configure agent with API key |
| `mcpshield scan` | Scan and report MCP servers |
| `mcpshield scan --dry-run` | Scan without reporting |
| `mcpshield daemon` | Run continuous scheduled scanning |
| `mcpshield status` | Show agent status |
| `mcpshield list` | List found servers (no report) |
| `mcpshield --version` | Show version |

## What It Scans

The agent looks for MCP server configurations in:

**Windows:**
- `%APPDATA%\Claude\claude_desktop_config.json`
- `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`

**macOS:**
- `~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux:**
- `~/.config/Claude/claude_desktop_config.json`
- `~/.config/cursor/mcp.json`

## What It Reports

For each discovered MCP server:

- **Server name** - e.g., "filesystem", "postgres"
- **Server type** - e.g., "@modelcontextprotocol/server-filesystem"
- **Command** - Full command string
- **Scope** - Access scope (file paths, URLs)
- **Environment variables** - Names only, NOT values
- **Status** - Active or dormant

## Configuration

Config is stored in:
- Windows: `%LOCALAPPDATA%\MCPShield\config.json`
- macOS/Linux: `~/.config/mcpshield/config.json`

```json
{
  "api_url": "https://api.mcpshield.app",
  "api_key": "mcp_sk_...",
  "scan_interval": 300
}
```

### Daemon Mode (Continuous Scanning)

Run the agent in daemon mode for automatic scheduled scanning:

```bash
# Default: scan every hour (3600 seconds)
mcpshield daemon

# Custom interval: scan every 5 minutes
mcpshield daemon --interval 300
```

The daemon will:
- Scan for MCP servers at the configured interval
- Report discovered servers to the backend
- Send heartbeat updates
- Log each scan cycle
- Shut down gracefully on Ctrl+C

Configure the default interval in your config file (`scan_interval` key).

## Security

- **Never sends credential values** - Only environment variable names
- **Local config is secure** - API key stored locally
- **HTTPS by default** - All API communication encrypted

## Development

```bash
# Install in development mode
pip install -e .

# Run tests
pytest

# Run locally against dev API
mcpshield configure --api-key YOUR_KEY --api-url http://localhost:8000
```

## License

MIT License - see LICENSE file.
