Metadata-Version: 2.4
Name: kbbi-mcp
Version: 0.1.0
Summary: A simple MCP server for querying KBBI (Indonesian dictionary)
Keywords: mcp,kbbi,dictionary,indonesian
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: mcp>=2.2.0,<3
Requires-Dist: beautifulsoup4>=4.12,<5
Requires-Dist: pydantic-settings>=2,<3
Requires-Dist: mcp-types>=2.2.0,<3
Requires-Python: >=3.13
Project-URL: Repository, https://github.com/gaato/kbbi-mcp
Project-URL: Issues, https://github.com/gaato/kbbi-mcp/issues
Description-Content-Type: text/x-rst

kbbi-mcp
========

.. image:: https://img.shields.io/github/actions/workflow/status/gaato/kbbi-mcp/ci.yml?label=CI
   :target: https://github.com/gaato/kbbi-mcp/actions/workflows/ci.yml
   :alt: CI

.. image:: https://img.shields.io/pypi/v/kbbi-mcp
   :target: https://pypi.org/project/kbbi-mcp/
   :alt: PyPI

.. image:: https://img.shields.io/pypi/pyversions/kbbi-mcp
   :target: https://pypi.org/project/kbbi-mcp/
   :alt: Python

.. image:: https://img.shields.io/pypi/l/kbbi-mcp
   :target: https://github.com/gaato/kbbi-mcp/blob/HEAD/LICENSE
   :alt: 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``

.. code-block:: 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/

To run the server over stdio directly from this checkout:

.. code-block:: bash

   uv run kbbi-mcp

To point an MCP client at this checkout, use an ``mcpServers`` entry like this
(replace the path with the absolute path of your clone):

.. code-block:: json

   {
       "mcpServers": {
           "kbbi-dev": {
               "command": "uv",
               "args": ["--directory", "/path/to/kbbi-mcp", "run", "kbbi-mcp"]
           }
       }
   }

Tool: ``kbbi_lookup``
---------------------

**Input**

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

Example tool arguments:

.. code-block:: json

   {
       "query": "makan"
   }

**Output**

Returns a JSON object:

- ``found`` (bool)
- ``query`` (string)
- ``url`` (string | null)
- ``entries`` (list)
- ``suggestions`` (list)

An empty query or a failed lookup (e.g. KBBI unreachable) is reported as an MCP tool error
(``isError: true``) with a message, not as a JSON payload.

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

.. code-block:: 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 (``application/json``).

- ``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``)
- ``KBBI_LOG_LEVEL`` (default: ``INFO``): level of the server's logs, written to stderr
