Metadata-Version: 2.4
Name: kbbi-mcp
Version: 0.0.4
Summary: A simple MCP server for querying KBBI (Indonesian dictionary)
Keywords: mcp,kbbi,dictionary,indonesian,fastmcp
Author: Gakuto Furuya
Author-email: Gakuto Furuya <57865205+gaato@users.noreply.github.com>
License-Expression: BlueOak-1.0.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: fastmcp>=2.14.1,<3
Requires-Dist: beautifulsoup4>=4.12,<5
Requires-Dist: pydantic-settings>=2,<3
Requires-Dist: ruff>=0.14.10 ; extra == 'dev'
Requires-Dist: ty>=0.0.7 ; extra == 'dev'
Requires-Dist: pytest>=8,<9 ; extra == 'dev'
Requires-Python: >=3.13
Project-URL: Issues, https://github.com/gaato/kbbi-mcp/issues
Project-URL: Repository, https://github.com/gaato/kbbi-mcp
Provides-Extra: dev
Description-Content-Type: text/markdown

# kbbi-mcp

[![CI](https://img.shields.io/github/actions/workflow/status/gaato/kbbi-mcp/ci.yml?label=CI)](https://github.com/gaato/kbbi-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/kbbi-mcp)](https://pypi.org/project/kbbi-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/kbbi-mcp)](https://pypi.org/project/kbbi-mcp/)
[![License](https://img.shields.io/pypi/l/kbbi-mcp)](https://github.com/gaato/kbbi-mcp/blob/HEAD/LICENSE)

An MCP server for querying KBBI (Kamus Besar Bahasa Indonesia / KBBI Daring).

**Python:** 3.13+

This project exposes a single, stable JSON tool output so LLM clients can decide how to format, translate, or summarize results.

## Relationship to KBBI Daring

This project is **unofficial** and is **not affiliated with** or endorsed by the official KBBI Daring service.

## Features

- MCP tool: `kbbi_lookup(query: str)`
- MCP resource: `kbbi://{query}` (same payload as `kbbi_lookup`)
- No login/auth flow required
- Uses official KBBI VI Daring by default

## Configure in an MCP client (JSON)

Most MCP clients (including Claude Desktop) use a JSON config with a top-level `mcpServers` object.
This `mcpServers` format is an emergent standard across the MCP ecosystem (see: https://gofastmcp.com/integrations/mcp-json-configuration.md).

### `mcpServers`-based clients (Claude Desktop / Cursor / Windsurf)

This matches the convention used by many Python MCP servers.

Where to put it:

- Claude Desktop: `~/.claude/claude_desktop_config.json`
- Cursor: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
- Windsurf: `~/.codeium/windsurf/mcp_config.json`

```json
{
	"mcpServers": {
		"kbbi": {
			"command": "uvx",
			"args": ["kbbi-mcp"]
		}
	}
}
```

Note: this example uses `uvx` (part of `uv`) to run the server.
Install uv here: https://docs.astral.sh/uv/getting-started/installation/

If you don't want to depend on `uv`, install `kbbi-mcp` into an environment and point your client to that environment's executable. For example:

- Use the console script (recommended when available): `kbbi-mcp`
- Or run the module: `python -m kbbi_mcp`

The server performs direct lookups to the official KBBI VI Daring site.

### Local development (run from this repo)

You'll need `uv` installed: https://docs.astral.sh/uv/getting-started/installation/

This repo includes a `fastmcp.json` file that defines how to run the server (source + uv environment + stdio transport).

To run the server directly from this checkout:

```bash
fastmcp run
```

To generate an `mcpServers` entry you can paste into your MCP client config:

```bash
fastmcp install mcp-json fastmcp.json
```

Note: the generated configuration uses absolute paths so it works regardless of the client's working directory.

## Tool: `kbbi_lookup`

**Input**

- `query` (string): a word or phrase

Example tool arguments:

```json
{
	"query": "makan"
}
```

**Output**

Returns a JSON object:

- `found` (bool)
- `query` (string)
- `url` (string | null)
- `entries` (list)
- `suggestions` (list)
- `error` (string, optional): present only when the request is invalid (e.g. empty query) or an unexpected error occurs

`entries` uses an English-key schema with normalization:

- `etymology` is always present (as an object or `null`)
- related-word lists are always present (as arrays, possibly empty)

This keeps tool output predictable across source variations.

Example tool output:

```json
{
	"found": true,
	"query": "makan",
	"url": "https://kbbi.kemendikdasmen.go.id/entri/makan",
	"entries": [
		{
			"headword": "makan",
			"sense_number": "",
			"root_words": [],
			"pronunciation": "",
			"nonstandard_forms": [],
			"variants": [],
			"definitions": [],
			"etymology": null,
			"derived_words": [],
			"compound_words": [],
			"proverbs": [],
			"idioms": []
		}
	],
	"suggestions": []
}
```

## Resource: `kbbi://{query}`

This server also exposes the same payload as a read-only MCP resource.

- `kbbi://makan`

For low-level debugging, a client would read it using `resources/read` with `{"uri": "kbbi://makan"}`.

## Data source

Lookup behavior:

- Official source: `https://kbbi.kemendikdasmen.go.id/entri/{query}`

Optional environment variables:

- `KBBI_BASE_URL` (default: `https://kbbi.kemendikdasmen.go.id`)
- `KBBI_TIMEOUT_SECONDS` (default: `10.0`)
