Metadata-Version: 2.4
Name: factors-mcp-v2
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-v2

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`)

## Install

### From the wheel (built locally)

```bash
cd factors_mcp_v2
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install dist/factors_mcp_v2-0.1.0-py3-none-any.whl
```

(Replace the wheel filename with the version produced under `dist/`.)

### Editable install (development)

```bash
cd factors_mcp_v2
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
```

The `factors-mcp-v2` console script is installed on your `PATH`.

## 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-v2`, 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": "/absolute/path/to/your/.venv/bin/python",
      "args": ["-m", "factors_mcp_v2"],
      "env": {
        "FACTORS_API_KEY": "your_private_token",
        "FACTORS_API_URL": "https://api.factors.ai"
      }
    }
  }
}
```

Alternatively, if `factors-mcp-v2` is on your `PATH` inside that venv:

```json
{
  "mcpServers": {
    "factors-ai": {
      "command": "/absolute/path/to/your/.venv/bin/factors-mcp-v2",
      "args": [],
      "env": {
        "FACTORS_API_KEY": "your_private_token",
        "FACTORS_API_URL": "https://api.factors.ai"
      }
    }
  }
}
```

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": "/absolute/path/to/your/.venv/bin/python",
      "args": ["-m", "factors_mcp_v2"],
      "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-v2` so the client does not pick up a different interpreter than the one where the package is installed.

## Build the wheel

From this directory (`factors_mcp_v2`):

```bash
python -m venv .venv
source .venv/bin/activate
pip install build
python -m build
```

Artifacts appear under `dist/`:

- `factors_mcp_v2-<version>-py3-none-any.whl`
- `factors_mcp_v2-<version>.tar.gz` (sdist)

## Run the MCP server

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

```bash
export FACTORS_API_KEY=your_private_token
export FACTORS_API_URL=https://api.factors.ai   # optional; default shown

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

Or:

```bash
python -m factors_mcp_v2
```

### 2. SSE over HTTP (remote / Docker-style)

The underlying `FastMCP` server supports `transport="sse"`. Set env vars and use the entry point; if you need SSE explicitly, run the same module with a small wrapper or extend `main()` in `server.py` to pass `transport="sse"` and `host`/`port` as needed.

For local Docker builds, the repo may use a `Dockerfile` that sets `FASTMCP_HOST` / `FASTMCP_PORT` and runs the server.

### 3. Run from the repo without installing (development only)

You must put the package on `PYTHONPATH` so `factors_mcp_v2` imports resolve:

```bash
cd factors_mcp_v2
export PYTHONPATH=src
export FACTORS_API_KEY=your_private_token
python src/factors_mcp_v2/server.py
```

Prefer `pip install -e .` and `factors-mcp-v2` or `python -m factors_mcp_v2` instead.

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `FACTORS_API_KEY` | _(required)_ | Private project token (Authorization header to `/mcp/afx/*`) |
| `FACTORS_API_URL` | `https://api.factors.ai` | Base URL of the Factors API |
| `FACTORS_BEARER_TOKEN` | _(empty)_ | Optional; reserved for future use |
| `FACTORS_SESSION_TOKEN` | _(empty)_ | Optional session-related env |

## Package layout

```
factors_mcp_v2/
  pyproject.toml
  README.md
  requirements.txt
  src/
    factors_mcp_v2/
      __init__.py
      __main__.py
      server.py          # MCP server (FastMCP tools, resources, prompts)
      utils.py
      AGENT_PROMPT_GUIDELINES.md
```

## License

Proprietary — Factors.ai internal use unless otherwise stated.
