# PelaPela

<img src="assets/logo.png" alt="PelaPela logo" width="120" />

Model response tuning for translation work — naturalness, tone, and script
guidance, parameterized by language pair. Ships as a Claude Code skill and
as an MCP server, so the same tuning methodology works in Claude, ChatGPT
(via MCP), and any other MCP-compatible host.

This tunes *how* a model phrases a translation — word choice, register,
script — not the translation engine itself. Point it at whatever model
you're already calling.

## Why

LLM translations often read as "translated" rather than natural: literal
transliteration of ordinary words, mismatched formality, wrong script for
the target audience. This package encodes a small, explicit set of rules
for catching that, plus a cheap self-check step (fix it yourself before
returning, rather than burning a second model call).

## Use in Claude Code

Install the plugin, then invoke per language pair with optional tone/script
args, in any order:

```
/pela:en-jp friendly kanaonly
/pela:en-es formal
```

Supported today: `en-jp`, `en-es`. See [Adding a pair](#adding-a-pair) to
extend it.

## Use via MCP (ChatGPT and other hosts)

ChatGPT's old Plugins system is deprecated; this ships as an MCP server
instead, which ChatGPT and most modern agent hosts support.

```bash
npx pelapela-mcp
```

Or point your MCP host's config at it directly:

```json
{
  "mcpServers": {
    "pelapela": { "command": "npx", "args": ["pelapela-mcp"] }
  }
}
```

It exposes one prompt and one tool, both named `pela_translate_tuning`,
taking `pair` (required), `tone` (optional, default `neutral`), and
`script` (optional, where the pair supports one).

### Hosted / remote MCP (ChatGPT Apps submission, other remote-only hosts)

`npx pelapela-mcp` above runs over stdio — fine for local hosts (Claude
Desktop, most CLI agents), but ChatGPT's app directory and some other hosts
require a public HTTPS `/mcp` endpoint instead. `worker/` has that variant,
built on Cloudflare Workers + the Agents SDK (`McpAgent`), same
`pela_translate_tuning` tool, same `core/buildTuning.mjs` source of truth —
just a different transport.

**Live:** `https://pelapela-mcp.jess-901.workers.dev/mcp`

```bash
cd worker
npm install
npm run dev      # local HTTP test at http://localhost:8788/mcp
npm run deploy   # publish to your own Cloudflare account
```

Submitting to ChatGPT's app/plugin directory beyond hosting it is a manual,
identity-verified process through OpenAI's own submission portal — not
something this repo can automate.

## Adding a pair

Everything lives in `core/buildTuning.mjs` — a single `PAIR_NOTES` entry per
pair (naturalness rules, tone notes, script variants where applicable). Add
an entry there, add a matching `skills/pela-<pair>/SKILL.md` following the
existing two as a template, and both the Claude skill and the MCP server
pick it up automatically (the MCP server reads `PAIRS` directly from the
same module — nothing to duplicate).

## Development

```bash
npm install
npm test                    # unit tests for the instruction builder
node tests/mcp-smoke.mjs    # real MCP client/server round-trip check
```

## License

MIT