Metadata-Version: 2.4
Name: crowdos-mcp
Version: 0.1.0
Summary: Model Context Protocol server for CrowdOS — synthetic focus groups as agent-callable tools.
Project-URL: Homepage, https://crowdos.ai
Project-URL: Documentation, https://crowdos.ai/developers
Project-URL: Repository, https://github.com/bjnagent/crowd
Project-URL: Issues, https://github.com/bjnagent/crowd/issues
Author-email: CrowdOS <support@crowdos.ai>
License: MIT
Keywords: ai-agents,anthropic,claude,crowdos,focus-group,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# CrowdOS MCP Server

Synthetic focus groups as agent-callable tools. Exposes the
[CrowdOS](https://crowdos.ai) developer API as
[Model Context Protocol](https://modelcontextprotocol.io) tools so AI
agents (Claude Desktop, Cursor, Cline, LangGraph, CrewAI, AutoGPT,
Devin, etc.) can run synthetic public-opinion research with a single
tool call.

## What this gives you

Your agent can now do things like:

```
> Run a focus group on whether companies should mandate 4-day weeks.
   Use 200 agents from the us_general_population preset.

[tool: run_focus_group]
{
  "id": "ad4b3736-...",
  "sentiment_summary": {
    "support_pct": 71.5, "oppose_pct": 18.0, "mixed_pct": 10.5
  },
  "sample_responses": [
    {"agent_name": "Maria Chen", "stance": "supports", ... },
    ...
  ]
}
```

## Installation

```bash
pip install crowdos-mcp
```

Then mint a free sandbox API key at <https://crowdos.ai/developers> —
no credit card required for the free tier (50 agents per study,
5 req/min).

## Configure for Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "crowdos": {
      "command": "crowdos-mcp",
      "env": {
        "CROWDOS_API_KEY": "crowd_..."
      }
    }
  }
}
```

Restart Claude Desktop. The CrowdOS tools should appear in the
slash-command picker.

## Configure for Cursor

Settings → MCP Servers → Add. Same env block as above; command =
`crowdos-mcp`.

## Configure for Cline (VS Code)

Settings → Cline → MCP Servers → Edit JSON:

```json
{
  "mcpServers": {
    "crowdos": {
      "command": "crowdos-mcp",
      "env": { "CROWDOS_API_KEY": "crowd_..." }
    }
  }
}
```

## Tools exposed

| Tool | What it does | Auth |
|---|---|---|
| `run_focus_group` | Synthetic poll on a topic, returns sentiment + quotes | required |
| `run_debate` | Multi-round synthetic debate, returns convergence | required |
| `list_demographic_presets` | Discover available audience templates | required |
| `get_simulation` | Fetch full results of a previously-run study | required |
| `crowd_sample` | Browse the public CrowdOS crowd (sanitized) | none |

`run_focus_group` and `run_debate` block 5–120s depending on
population size — that's a real synthetic-research call running
behind the scenes, not a cached response. The MCP server returns a
trimmed envelope (sentiment summary + first 5 representative quotes
+ billing breakdown). Use `get_simulation` to pull the full payload
when you need every agent's full reasoning.

## Configuration

| Env var | Default | Required |
|---|---|---|
| `CROWDOS_API_KEY` | — | yes (except `crowd_sample`) |
| `CROWDOS_API_BASE_URL` | `https://api.crowdos.ai` | no |

## Cost

CrowdOS uses a metered wallet. The MCP server returns the actual
debit on every successful call inside `billing.actual_cents`. Free
tier ships with $5 of credit; top up at <https://crowdos.ai/account/billing>
once it runs out.

Free-tier monthly quota is 120k tokens (~3 large studies). Pro tier
removes the cap.

## Programmatic use (without an MCP host)

The server is also a regular Python module:

```bash
python -m crowdos_mcp
# stdio MCP server, waits for messages on stdin
```

Or import and embed:

```python
from crowdos_mcp.server import build_server
server = build_server()
# server is a configured mcp.server.Server instance
```

## Versioning

Follows semver. The MCP tool surface (tool names, input schemas) is
stable; additive changes (new tools, new optional fields) ship as
minor versions. Removing or renaming a tool is a major version.

## License

MIT.

## Issues / questions

<https://github.com/bjnagent/crowd/issues>
