Metadata-Version: 2.4
Name: insightaid-mcp
Version: 1.1.0a0
Summary: Model Context Protocol server for InsightAId — survey lifecycle for AI coding agents (Claude Code, Codex CLI, GitHub Copilot)
Project-URL: Homepage, https://insightaid.ai
Project-URL: Documentation, https://insightaid.ai/docs/mcp
Project-URL: Source, https://github.com/umignozzetti/insightaid-mcp
Project-URL: Issues, https://github.com/umignozzetti/insightaid-mcp/issues
Project-URL: Umbrella tracker, https://github.com/umignozzetti/insight-aid/issues/88
Author-email: "InsightAId, Inc." <ops@insightaid.ai>
License: Proprietary
Keywords: claude-code,insightaid,mcp,model-context-protocol,survey
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: mcp>=1.2
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.7
Requires-Dist: structlog>=24
Requires-Dist: tenacity>=8.5
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# insightaid-mcp

Model Context Protocol server that exposes the [InsightAId](https://insightaid.ai)
survey lifecycle to AI coding agents — Claude Code, Codex CLI, GitHub Copilot —
via 9 workflow-shaped tool verbs.

Status: **v1.1 alpha** (post-launch ship; not yet on PyPI).

See `CLAUDE.md` for project guidance, `docs/decisions.md` for the
architectural rationale, `checklist_machine.md` for the implementation
status. Umbrella issue: <https://github.com/umignozzetti/insight-aid/issues/88>.

## Install (once published)

```bash
pip install insightaid-mcp
```

## Configure

Mint a Personal Access Token at <https://insightaid.ai/app/settings?tab=pats>
(plaintext shown ONCE — copy it then). Add to your client config:

**Claude Code** (`~/.claude.json`):

```json
{
  "mcpServers": {
    "insightaid": {
      "command": "insightaid-mcp",
      "env": { "INSIGHTAID_PAT": "iaid_pat_..." }
    }
  }
}
```

**Codex CLI** / **GitHub Copilot** — see their MCP-config docs; the entry
point is the same `insightaid-mcp` command.

## Tools (v1.1)

Workflow-shaped, not CRUD. Nine verbs:

```
auth.whoami()
survey.author_and_validate(brief, project_id?)
survey.publish(instrument_id)
survey.deploy_to_humans(instrument_id, channel, n)
survey.deploy_to_farm(instrument_id, n, profile?)         # n >= 50 enforced
survey.run_status(run_id)
survey.results(run_id, format='summary'|'raw')
survey.cancel(run_id)
workspace.list_my_work()
```

## Development

```bash
# Editable install with dev deps
pip install -e ".[dev]"

# Run tests
pytest tests/

# Lint + type-check
ruff check src/ tests/
mypy src/
```

## Security

PAT scopes are workspace-bound and least-privilege:
`instruments:read`, `instruments:write`, `runs:read`, `runs:write`,
`responses:read`. Revoke at the dashboard.

The MCP server holds **zero api secrets** — only the PAT loaded from
`INSIGHTAID_PAT` env. Token format `iaid_pat_<KID>_<base32url>`; lookup
is HMAC-SHA256 with a server-side pepper that never leaves the api host.

Report security issues to <ops@insightaid.ai>.

## License

Proprietary — InsightAId, Inc. All rights reserved.
