# Sellable Admin MCP

Internal Sellable Admin MCP server for team operations, fulfillment workflows,
and cross-workspace support tools.

This package is installed through the Sellable Admin installer and expects
runtime configuration from `SELLABLE_ADMIN_HOME` or
`SELLABLE_ADMIN_CONFIG_PATH`. Do not include secrets in this package.

The server advertises exactly 46 Admin tools. Lightfield is not an Admin MCP
tool surface; configured Hermes Admin profiles use the separate remote alias
`lightfield`. The internal Lightfield runner remains only for the onboarding
handoff reader.

## Hermes Desktop Command Discovery

Hermes uses the packaged skills here as the source material for
`/sellable-admin-*` commands. The installer rewrites those skills for Hermes
and registers the profile skill directory in the gateway root config with
`skills.external_dirs`; this is what makes the commands visible in Desktop
autocomplete.

When changing Admin MCP tools or skills, publish both packages:

- `@sellable/admin-mcp` for the MCP server and packaged skills.
- `@sellable/admin-install` for the Hermes/Codex/Claude installer runtime
  snapshot.

Do not move the Hermes `skills.external_dirs` behavior into the Codex or Claude
install paths. Those existing installs are managed by `scripts/install-local-mcp.mjs`.

Hermes Desktop also needs the dashboard server itself to run in the
`sellable-admin` profile. The Admin installer writes the generated
`/opt/data/bin/entrypoint-sellable-admin.sh` wrapper for the Hostinger profile;
Docker Compose should keep using that entrypoint so the dashboard starts with
`hermes -p sellable-admin dashboard --isolated ...`. MCP success alone is not
proof that Desktop slash commands are visible.

## Google Workspace Skill

The packaged `gws-workspace` skill routes Calendar, Gmail, Drive, Docs, Sheets,
and contact requests through the host's existing Google Workspace integration.
Calendar uses the Sellable Admin service-account credential through the GWS
CLI and supports reads plus approved writes. Gmail and broader user-scoped
Workspace services use the Hermes OAuth wrapper. The skill preserves explicit
approval before external mutations and the stricter Gmail send gate.

## Contact Lookup Tools

Use these explicit tools when Shermeen or another admin caller needs one contact
type:

- `admin_find_contact_email`: find a prospect email.
- `admin_find_contact_phone_number`: find a prospect phone number.

Both tools call the Sellable Prospeo contact lookup route for the sellable.dev
workspace and use cached `EnrichedProspect` values first, so cache hits do not
spend credits. Pass `enrichedProspectId` when you have it; otherwise pass known
person/company identifiers in `data`.

Prospeo matching notes:

- Prefer `firstName` + `lastName` with `companyWebsite` or
  `companyLinkedinUrl` when possible. LinkedIn profile URLs are supported, but
  company context improves live vendor matching.
- `personId` means a Prospeo Search Person API `person_id` only. Do not pass
  LinkedIn member/internal IDs, Sellable `LinkedInPerson` IDs, or Unipile IDs.
- `companyWebsite` may be a bare domain such as `deloitte.com` or a full URL;
  this MCP normalizes bare domains before calling the Sellable backend.
- Prospeo charges 1 credit per email found and 10 credits per mobile found.
  Email is included when mobile is requested, and no result means no vendor
  credits used.

Email example:

```json
{
  "workspaceId": "cmj0wv9pe02jx23xdv6wfhg9x",
  "enrichedProspectId": "prospect_123",
  "onlyVerifiedEmail": true,
  "data": {
    "linkedinUrl": "https://www.linkedin.com/in/example",
    "fullName": "Example Person",
    "companyName": "Example Co",
    "companyWebsite": "example.com"
  }
}
```

Phone example:

```json
{
  "workspaceId": "cmj0wv9pe02jx23xdv6wfhg9x",
  "enrichedProspectId": "prospect_123",
  "onlyVerifiedMobile": true,
  "data": {
    "linkedinUrl": "https://www.linkedin.com/in/example",
    "fullName": "Example Person",
    "companyName": "Example Co",
    "companyWebsite": "example.com"
  }
}
```

Use `forceRefresh: true` only when you intentionally want to bypass cached
contact values and potentially spend credits.