Metadata-Version: 2.4
Name: verbumia-mcp
Version: 0.12.1
Summary: Model Context Protocol server for Verbumia — list projects, missing keys, propose translations from Claude Desktop and other MCP clients.
Project-URL: Homepage, https://verbumia.ca
Project-URL: Documentation, https://verbumia.ca/docs/mcp/setup
Project-URL: Source, https://github.com/verbumia/verbumia-tools
Project-URL: Issues, https://github.com/verbumia/verbumia-tools/issues
Author: Verbumia
License: MIT
License-File: LICENSE
Keywords: claude,i18n,mcp,translations,verbumia
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Internationalization
Requires-Python: <3.14,>=3.12
Requires-Dist: httpx>=0.28
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.9
Description-Content-Type: text/markdown

# Verbumia MCP server

Model Context Protocol server for [Verbumia](https://verbumia.ca) — exposes
your translation project to Claude Desktop and other MCP clients.

## Status

Thirteen tools wired: `list_projects`, `get_project_info`, `list_keys`,
`list_untranslated_keys`, `list_missing_keys`, `missing_keys_stats`,
`acknowledge_missing_keys`, `create_key`, `propose_translation`,
`publish_cdn`, `validate_translations`, `project_context_get`,
`project_context_set`.

### Project context document (V1.2)

`project_context_get` / `project_context_set` read and write a free-form
markdown blob attached to the project — terminology, brand voice, domain
notes (religious, legal, medical, gaming, etc.). The content is intended
as ambient context for human translators **and** for AI agents producing
translations: prepend it to your translation prompts so every output stays
consistent with the project's vocabulary and tone. Hard cap 100 KiB.

Scopes:
- `project_context_get` requires `project:read` (existing scope).
- `project_context_set` requires `project:settings:write` (new scope, narrower
  than `project:write` since settings changes propagate to every translator's
  prompt context).

Note: the blanket `mcp:*` scope is **not** sufficient for these tools — grant
the precise scope on the key.

## Install

```bash
# Recommended (zero-install, used by Claude Desktop's mcp.json):
npx -y @verbumia/mcp

# Or from PyPI:
pipx install verbumia-mcp
```

A Homebrew tap (`brew install verbumia/tap/verbumia-mcp`) is coming once we
publish to npm.

## Configure (Claude Desktop)

Open **Settings → Developer → Edit Config**, then:

Single-project setup:

```json
{
  "mcpServers": {
    "verbumia": {
      "command": "npx",
      "args": ["-y", "@verbumia/mcp"],
      "env": {
        "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
        "VERBUMIA_PROJECTS": "<project_uuid>",
        "VERBUMIA_BASE_URL": "https://api.verbumia.dev"
      }
    }
  }
}
```

Multi-project setup (v0.11+) — comma-separate the UUIDs and Claude will pass
`project_uuid` on each tool call:

```json
"env": {
  "VERBUMIA_API_KEY": "vrb_live_<prefix>.<secret>",
  "VERBUMIA_PROJECTS": "01993a..,01993b..,01993c.."
}
```

Restart Claude Desktop. Tools show up in the prompt UI.

## Environment

| Variable             | Required | Default                        | Description                                                                                |
|----------------------|----------|--------------------------------|--------------------------------------------------------------------------------------------|
| `VERBUMIA_API_KEY`   | yes      |                                | API key from Org Settings → API Keys (`VERBUMIA_TOKEN` also accepted, back-compat)         |
| `VERBUMIA_PROJECTS`  | no       | (LLM passes per call)          | CSV of project UUIDs. When >1, the LLM MUST pass `project_uuid` on each tool call.         |
| `VERBUMIA_PROJECT`   | no       | (legacy)                       | Singular fallback for v0.10.x users. Ignored when `VERBUMIA_PROJECTS` is set (warns).      |
| `VERBUMIA_BASE_URL`  | no       | `https://api.verbumia.dev`      | Override for self-host or staging (`VERBUMIA_API_BASE` also accepted, back-compat)         |

The token format is `vrb_live_<prefix>.<secret>` and must carry the `mcp:*`
scope. For the `project_context_*` tools, also grant `project:read` and/or
`project:settings:write` — see the **Project context document** section
above. Treat the token like any other secret — keychain or `.env`, never
commit.

If your API key is pinned to a single project (its `project_uuid` is set
server-side), listing additional UUIDs in `VERBUMIA_PROJECTS` will surface
as a `403 API key is scoped to a different project` from the backend on
any call targeting one of the others.

## Local development

```bash
cd mcp
uv sync
uv run verbumia-mcp        # stdio transport — pipe MCP frames over stdin/stdout
```

## License

MIT.
