# namakan-mcp-crm

Internal MCP server: one CRM tool surface for Namakan agents. They call `crm_find_contact` whether the plant runs HubSpot, Salesforce, Dynamics, Pipedrive, or Zoho.

The client never configures MCP. `integration-engineer` (and `delivery-manager`, `solution-architect`, `data-engineer`, `agent-systems-engineer`) get this server from bootstrap. Writes stay off until `ciso` approves.

## How agents connect

```yaml
mcp_servers:
  namakan-mcp-crm:
    command: uvx
    args:
      - --from
      - git+https://github.com/cfollette18/namakan-mcp-crm.git
      - namakan-mcp-crm
      - serve
    env:
      NAMAKAN_CRM_BACKEND: mock
    trust: full
```

Swap `NAMAKAN_CRM_BACKEND` per engagement in `clients/<slug>/` config — never by teaching the agent a vendor API.

## Architecture

![integration-engineer to MCP to CRM tools to mock or vendor. Writes off until CISO](docs/architecture.svg)

## Full AI workflow

![Find contact, find account, list deals, then a blocked write](docs/workflow.svg)

Playbook path (`playbooks/phase-2-erp-crm-automation.md`):

1. `integration-engineer` is assigned the connector card.
2. Agent calls `crm_run_workflow` (or the individual `crm_*` tools).
3. The last step is a **blocked write**. That is the demo, not a failure.
4. Production writes require `NAMAKAN_MCP_ALLOW_WRITES=1`, dry-run, and `ciso`.

Demo without an agent process:

```bash
namakan-mcp-crm workflow
```

Expected: four JSON steps. Last step `"error": "writes_disabled"`.

## Tools

| Tool | Read/write | Arguments |
|---|---|---|
| `crm_find_contact` | read | `query` |
| `crm_find_account` | read | `query` |
| `crm_list_deals` | read | `account_id?` |
| `crm_get_deal` | read | `deal_id` |
| `crm_create_deal` | write | `name`, `account_id?`, `amount?`, `stage?` |
| `crm_log_activity` | write | `note`, `contact_id?`, `deal_id?` |
| `crm_run_workflow` | read + blocked write | `use_case?`, `query?` |

## Potential use cases

![Who owns this account, open Phase 2 pipeline, log the plant visit](docs/usecases.svg)

| Use case | Which agent | Why it matters |
|---|---|---|
| Who owns this account? | `integration-engineer` | Same tool on HubSpot today and Salesforce after a migration. |
| Open Phase 2 pipeline | `vp-sales` via assigned IC | Mock data ships; no token needed to rehearse the call. |
| Log the plant visit | `delivery-manager` | Stays blocked until writes are enabled and `ciso` signs off. |

`use_case`: `who-owns-account` (default), `open-pipeline`, `log-plant-visit`.

## Tests

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT. Copyright (c) 2026 Namakan AI Engineering.