Metadata-Version: 2.4
Name: realnex-mcp
Version: 0.5.0
Summary: Model Context Protocol server for RealNex CRM.
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tenacity>=8.0
Requires-Dist: typing-extensions>=4.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# realnex-mcp

A Model Context Protocol (MCP) server that lets Claude talk to a RealNex CRM in plain English.

This is a **monorepo** containing two related Python packages:

- `realnex_api_client` — a thin Python wrapper around the RealNex Sync API (auth, requests, OData query building, retry/backoff). Reusable on its own.
- `realnex_mcp_server` — wraps the API client and exposes 12 tools to Claude via MCP. The thing end-users actually install.

The intent is that the same `realnex_api_client` is later reused by `realnex-automation-templates` (v1.0 — webhook receivers, lead-form pipelines, etc.) so we never have two copies of the API code.

## Status

**v0.1 — pre-alpha, scaffolding only.** See `../realnex_mcp_scoping.md` for the architecture and tool plan.

## Install (end users)

See **[docs/install.md](docs/install.md)** for the full walkthrough. Short version:

1. Generate an API token in RealNex: **Settings → Admin → User Management → API Token**
2. `pip install realnex-mcp`
3. Add the config block (see [examples/claude_desktop_config.json](examples/claude_desktop_config.json)) to your Claude Desktop config and paste your token in
4. Restart Claude. Ask: *"who am I logged in as on RealNex?"*

The token inherits your user's exact RealNex permissions — if you can't delete a contact in the web UI, the API can't either. Admins can generate tokens on behalf of users who don't have permission to do it themselves.

## Local dev

```bash
# Recommended: uv (fast Python package manager)
uv venv
uv pip install -e ".[dev]"

# Run the MCP server in stdio mode for testing
python -m realnex_mcp_server
```

## Layout

```
realnex-mcp/
├── packages/
│   ├── realnex_api_client/       # the foundation lib
│   └── realnex_mcp_server/       # the MCP wrapper
├── examples/
│   ├── claude_desktop_config.json
│   └── example_prompts.md
├── docs/
├── tests/
└── pyproject.toml
```

## License

MIT (open-source; commercial setup/support/customization is the revenue layer).
