Metadata-Version: 2.4
Name: vendus-mcp
Version: 0.3.0
Summary: Model Context Protocol server for the Vendus AI sales platform
Project-URL: Homepage, https://github.com/Agentibus-ai/vendus
Project-URL: Documentation, https://github.com/Agentibus-ai/vendus/tree/main/mcp-server#readme
Project-URL: Issues, https://github.com/Agentibus-ai/vendus/issues
Project-URL: Source, https://github.com/Agentibus-ai/vendus/tree/main/mcp-server
Author-email: Agentibus <info@agentibus.ai>
Maintainer-email: Pietro Del Franco <info@agentibus.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,claude,claude-code,crm,mcp,model-context-protocol,sales,vendus
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: uvicorn>=0.24
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# vendus-mcp

[Model Context Protocol](https://modelcontextprotocol.io) server for the
Vendus AI sales platform. It lets any MCP-aware client (Claude Code, Claude
Desktop, Cursor, custom agents) read leads, conversations, agents, metrics
and knowledge base documents from a Vendus tenant via the public REST API.

V1 is read-only and scoped per API key.

## Quick start

```bash
# 1. Create an API key in your Vendus dashboard (Settings > API Keys)
# 2. Run the MCP server with uvx — no install required
VENDUS_API_KEY=vnd_live_xxx \
  VENDUS_BASE_URL=https://your-vendus-instance.fly.dev \
  uvx vendus-mcp
```

The server speaks MCP over stdio, so any compliant client can mount it.

## Configuration

| Env var            | Required | Default                                          | Description                                  |
| ------------------ | -------- | ------------------------------------------------ | -------------------------------------------- |
| `VENDUS_API_KEY`   | yes      | —                                                | API key issued from Settings > API Keys      |
| `VENDUS_BASE_URL`  | no       | `https://semory-dashboard-backend.fly.dev`       | Base URL of your Vendus backend              |

Keys are tenant-scoped and bound to a set of read scopes. Calls fail closed
when a scope is missing — there is no implicit elevation.

## Use it from Claude Code

Add the server to your project's `.mcp.json` (or to the global Claude Code
config):

```json
{
  "mcpServers": {
    "vendus": {
      "command": "uvx",
      "args": ["vendus-mcp"],
      "env": {
        "VENDUS_API_KEY": "vnd_live_xxx",
        "VENDUS_BASE_URL": "https://your-vendus-instance.fly.dev"
      }
    }
  }
}
```

Then run `claude mcp list` and you should see `vendus` reporting
`✓ Connected`. The tools become available inside any Claude Code session
in that project.

## Use it from Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
and add the same `mcpServers.vendus` block. Restart Claude Desktop.

## Use it from Cursor / Continue / other MCP clients

Any client that can launch a stdio MCP server works. Point it at
`uvx vendus-mcp` with the env vars above.

## Host it for Claude.ai Custom Connectors and ChatGPT remote MCP

Claude.ai and ChatGPT both accept a hosted MCP endpoint instead of a stdio
binary. The same package ships a streamable-HTTP variant:

```bash
VENDUS_BASE_URL=https://your-vendus-instance.fly.dev \
  uvx vendus-mcp-http --host 0.0.0.0 --port 8080 --mount-path /mcp
```

Authentication is **per-request**: the client (Claude / ChatGPT) forwards
the user's token in `Authorization: Bearer <vnd_live_...>` on every MCP
request, so a single deployment safely serves many tenants. `VENDUS_API_KEY`
is **not** read in HTTP mode — each caller brings their own.

Register the endpoint:

- **Claude.ai:** Settings → Connectors → *Add custom connector* → URL
  `https://your-host/mcp`, auth `Bearer` with the user's Vendus API key.
- **ChatGPT:** Settings → Apps & Connectors → *Add remote MCP server* →
  same URL + Bearer.

For the path to the **official** connector directories (OAuth 2.1 + DCR +
business registration), see
[`docs/superpowers/specs/2026-04-17-mcp-connector-directory.md`](../docs/superpowers/specs/2026-04-17-mcp-connector-directory.md).

## Tools

| Tool                       | Description                                          |
| -------------------------- | ---------------------------------------------------- |
| `list_leads`               | Filter by status, qualified, search, date range      |
| `get_lead`                 | Lead profile by id                                   |
| `get_conversations`        | Chronological messages for a lead                    |
| `list_agents`              | All AI agents on the tenant                          |
| `get_agent`                | Agent profile by id                                  |
| `get_metrics_summary`      | Funnel counters since a date                         |
| `get_metrics_funnel`       | Conversion percentages per stage                     |
| `list_knowledge_documents` | Knowledge base documents, paginated                  |
| `get_knowledge_document`   | Document metadata by id                              |

All tools return JSON strings shaped like `{"data": ...}` or
`{"error": {"code": "...", "message": "...", "status": 4xx}}` on failure.

## Local install (for hacking)

```bash
git clone https://github.com/Agentibus-ai/vendus
cd vendus/mcp-server
pip install -e ".[dev]"
pytest
```

## Roadmap

- Write tools (`leads:write`, `conversations:write`) once the REST API exposes them.
- HTTP-streamable transport for hosted Anthropic / OpenAI connectors.
- Webhook subscription tools.

## License

MIT — see [`LICENSE`](LICENSE).
