Metadata-Version: 2.4
Name: verbumia-mcp
Version: 0.10.0
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-mcp
Project-URL: Issues, https://github.com/verbumia/verbumia-mcp/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

Eleven 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`.

## 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:

```json
{
  "mcpServers": {
    "verbumia": {
      "command": "npx",
      "args": ["-y", "@verbumia/mcp"],
      "env": {
        "VERBUMIA_TOKEN": "vrb_live_<prefix>.<secret>",
        "VERBUMIA_PROJECT": "<project_uuid>",
        "VERBUMIA_API_BASE": "https://api.verbumia.ca"
      }
    }
  }
}
```

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

## Environment

| Variable           | Required | Default                        | Description                              |
|--------------------|----------|--------------------------------|------------------------------------------|
| `VERBUMIA_TOKEN`   | yes      |                                | API key from Org Settings → API Keys     |
| `VERBUMIA_PROJECT` | no       | (LLM passes per call)          | Default project context                   |
| `VERBUMIA_API_BASE`| no       | `https://api.verbumia.ca`      | Override for self-host or staging        |

The token format is `vrb_live_<prefix>.<secret>` and must carry the `mcp:*`
scope. Treat it like any other secret — keychain or `.env`, never commit.

## Local development

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

## License

MIT.
