dictlookup
README.md
# dictlookup
Words rarely sit in one language only. dictlookup is a small local bridge to the hosted kasahorow MCP service: you give it a word or short phrase together with your language and the word's language, and it returns the dictionary entry — definitions annotated with parts of speech — from the kasahorow dictionary (WOAKA).
Nothing is stored or computed on your own machine. This package answers `tools/list` locally from the captured tool definition and forwards every `tools/call` to the hosted service over a streamable-HTTP JSON-RPC session, returning whatever the service sends back unchanged.
This is a labelled subset rebuild: the upstream capture enumerates two tools, and only `lookup_word` is built here. The other captured tool, `validate_translation`, is omitted — it is a paid reading whose reply returns a payment link — and it is not registered, not served in `tools/list`, and not available on the CLI.
## The tools
- **`lookup_word`** — Looks up a word or short phrase in the kasahorow dictionary. `word` is the word or phrase, `fl` is your language (an ISO code such as `en`), and `tl` is the language of the word (an ISO code such as `ak` or `sw`). All three are required. Returns definitions with parts of speech.
## Install and run
As an MCP server via npm:
```bash
npx -y @reneturcios/dictlookup mcp
```
MCP client configuration:
```json
{
"mcpServers": {
"dictlookup": {
"command": "npx",
"args": ["-y", "@reneturcios/dictlookup", "mcp"]
}
}
}
```
As a container:
```bash
docker run -i ghcr.io/cloudcorprecords/dictlookup
docker run --rm ghcr.io/cloudcorprecords/dictlookup lookup_word '{"word":"akwaaba","fl":"en","tl":"ak"}'
```
## CLI
One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:
```bash
dictlookup lookup_word '{"word":"akwaaba","fl":"en","tl":"ak"}'
dictlookup --version
```
Exit codes: `0` when the forwarded call succeeds, `1` when the upstream result is an error, and `2` for usage problems such as an unknown subcommand or a malformed JSON argument.
## Configuration
- `KASAHOROW_MCP_URL` — Overrides the upstream endpoint. The default is the pinned hosted endpoint, `https://nabanya.kasahorow.com/mcp`. (The override variable is a reconstruction added by this rebuild.)
- `KASAHOROW_ACCESS_KEY` — When set, its value is sent to the upstream on every request as an `X-Kasahorow-Access: <value>` header. When it is not set, no such header is sent.
- `KASAHOROW_EMAIL` — When set, its value is sent to the upstream on every request as an `X-Kasahorow-Email: <value>` header. When it is not set, no such header is sent. (The header names are pinned by the registry record; the env forwarding is a reconstruction added by this rebuild, and the tool surface was captured keyless.)
Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with `dictlookup error:`.
## How forwarding works
The first forwarded call opens a session: an `initialize` request (protocol version `2025-03-26`), followed by a `notifications/initialized` notification, then the `tools/call` itself. If the service answers the initialize request with an `Mcp-Session-Id` header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any `isError` flag and any extra fields the service includes.
## Development
```bash
npm install
npm run build # tsc -> dist/ (dist/cli.js is the bin)
npm test # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev # run the CLI from source
```
The test suite checks the served tool list against the captured surface, asserts the omitted `validate_translation` tool is absent at the registry, MCP and CLI levels, exercises the session handshake and its reuse, covers both forwarding-header branches for the access key and the email, and verifies that arguments go upstream untouched and results come back untouched.
## License
MIT — see `LICENSE`. Copyright (c) 2026 Rene Turcios.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues