Metadata-Version: 2.4
Name: factors-mcp
Version: 0.1.0
Summary: Factors.ai MCP server — agent management and execution tools
License: Proprietary
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# factors-mcp

Python package exposing a **Model Context Protocol (MCP)** server for Factors.ai — list/create/update agents, run agents against domains, and use bundled prompt guidelines.

## Requirements

- Python 3.10+
- A Factors **private API token** (`FACTORS_API_KEY`) with access to the Factors API (`FACTORS_API_URL`)

## Client configuration (Claude Desktop & Cursor)

Both clients drive the server over **stdio**. Point them at the Python interpreter or console script from the **same virtualenv** where you installed `factors-mcp`, and pass your API credentials in **`env`** (do not commit real keys into shared project files).

### Claude Desktop

1. Quit Claude Desktop completely.
2. Open the config file in a text editor:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
3. Merge the `mcpServers` entry below with any existing `mcpServers` object (do not remove other servers).

```json
{
  "mcpServers": {
    "factors-ai": {
      "command": "python3",
      "args": ["-m", "factors_mcp"],
      "env": {
        "FACTORS_API_KEY": "your_private_token"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

### Cursor

1. Create or edit an MCP config file (JSON):
   - **Project:** `<repo-root>/.cursor/mcp.json` (optional; share with the team without secrets)
   - **User-wide:** `~/.cursor/mcp.json` (macOS/Linux) or `%USERPROFILE%\.cursor\mcp.json` (Windows)
2. Add a `mcpServers` entry (merge with existing servers if the file already exists).

```json
{
  "mcpServers": {
    "factors-ai": {
      "command": "python3",
      "args": ["-m", "factors_mcp"],
      "env": {
        "FACTORS_API_KEY": "your_private_token",
        "FACTORS_API_URL": "https://api.factors.ai"
      }
    }
  }
}
```

Fully restart Cursor after changing MCP configuration so it reloads the server list.

**Tip:** Use absolute paths to `python` or `factors-mcp` so the client does not pick up a different interpreter than the one where the package is installed.

## Run the MCP server

### 1. After installing the package (recommended)

```bash
export FACTORS_API_KEY=your_private_token 

# Default transport is stdio (typical for Cursor / Claude Desktop)
factors-mcp
```

Or:

```bash
python3 -m factors_mcp
```

## License

Proprietary — Factors.ai internal use unless otherwise stated.
