# Bareun MCP Server — Korean NLP & Spell/Grammar Checking

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![smithery badge](https://smithery.ai/badge/gih2yun/bareunai)](https://smithery.ai/servers/gih2yun/bareunai)

> **바른(Bareun)** is a Korean natural-language platform. This is its **MCP (Model
> Context Protocol)** server — it lets any MCP-compatible AI tool (Claude, Cursor,
> VS Code, Claude Desktop, …) perform **Korean morphological analysis** and
> **spell/grammar correction** by calling Bareun as a tool.

Large language models still miss the subtle spacing, particle agreement, and
confusable-word rules of Korean. Plug Bareun in as an MCP tool and your agent can
hand off analysis and proofreading to a dedicated Korean engine, then use the
result to produce more accurate Korean output.

- **Hosted endpoint:** `https://api.bareun.ai/mcp`
- **Transport:** Streamable HTTP (JSON-RPC 2.0) — no SSE, no extra port, no install
- **Auth:** API key (`api-key` header or `Authorization: Bearer <key>`)
- **Get an API key:** https://bareun.ai

> The `/mcp` endpoint is available on the **spell-checker–included** build of Bareun
> (the morphological-analysis-only build does not expose `/mcp`). The same endpoint
> works on self-hosted/on-prem installs — just swap the host.

---

## What it looks like

**Spelling & spacing — `correct_grammar`** (real output from `https://api.bareun.ai/mcp`):

| | |
|---|---|
| **In** | 회의결과를 정리해서 내일까지 보내주시기 바람니다. |
| **Out** | 회의 결과를 정리해서 내일까지 보내 주시기 바랍니다. |

Every fix comes back as a block, so an agent can explain the edit instead of silently
rewriting the sentence:

| Original | Corrected | Category | Rule |
|---|---|---|---|
| 회의결과를 | 회의 결과를 | `SPACING` | compound noun spacing |
| 보내주시기 | 보내 주시기 | `SPACING` | auxiliary-verb spacing |
| 바람니다. | 바랍니다. | `TYPO` | misspelling |

**Morphological analysis — `analyze_syntax`** (`format: compact`):

| | |
|---|---|
| **In** | 나는 학교에 간다. |
| **Out** | `나/NP 는/JX 학교/NNG 에/JKB 가/VV ㄴ다/EF ./SF` |

**Homograph senses — `analyze_syntax` with `with_sense: true`** (_beta_): 배 in 배가 아프다
comes back with `senseNo: 1` and its dictionary definition — 사람이나 동물의 몸에서 …
가슴과 엉덩이 사이의 부위 (*belly*, probability 0.87), plus the Urimalsaem entry id — so the
agent knows which 배 it is reading.

---

## Tools

| Tool | What it does | Key inputs |
|---|---|---|
| `analyze_syntax` | Splits a sentence into words/morphemes and tags parts of speech (morphological analysis). | `text` (required), `auto_split_sentence`, `auto_spacing`, `auto_jointing`, `custom_dict_names`, `encoding`, `format` (`full`\|`compact`), `with_sense` |
| `analyze_syntax_raw` | Same analysis **without post-processing** (no compound-noun/verb splitting, no auto spacing, no custom dictionaries) — the raw model output. | `text` (required), `auto_split_sentence`, `encoding`, `format`, `with_sense` |
| `search_dict` | Searches the Urimalsaem Korean dictionary (~1.1M entries) by **jamo (phoneme-level) slot patterns** — conditions like "verbs whose stem ends in the ㅎ coda" or "words ending in -아지" that cannot be expressed with composed Hangul syllables. | `pattern` (required), `anchor` (`word`\|`prefix`\|`suffix`\|`contains`), `pos`, `std_only`, `with_definition`, `limit`, `count_only` |
| `tokenize` | Splits a sentence into word (token) units. | `text` (required), `auto_spacing`, `encoding` |
| `correct_grammar` | Corrects spelling/spacing and returns correction blocks. | `text` (required), `custom_dict_names`, + 9 boolean correction options |
| `list_pos_tags` | Returns the 47 part-of-speech tags Bareun uses (code · name · class). | _(none)_ |

**`correct_grammar` options** (all boolean, default off): `treat_as_title`,
`disable_split_sentence`, `disable_caret_spacing`, `disable_vx_spacing`,
`enable_limited_punctuation`, `disable_confusion`, `enable_cleanup_whitespace`,
`disable_typo_correction`, `enable_sentence_check`.

**`encoding`** controls the unit for morpheme offsets: `utf32` (default, code points
— matches Python), `utf16` (JS/Java), `utf8` (bytes — Go/C++).

**`with_sense` — homograph sense disambiguation (WSD, _beta_).** Korean writes many
unrelated words identically: 배 can be *belly*, *ship*, or *pear*. Set `with_sense: true`
on `analyze_syntax`/`analyze_syntax_raw` and each content morpheme carries a `sense`
object — the dictionary sense number, its Korean definition, the Urimalsaem entry id, and
the probability of the chosen sense among that word's candidate senses. It is **off by
default** (one extra model pass; responses are byte-identical to before when omitted),
and `format=compact` renders it inline as `배__002/NNG`. This feature is in **beta** and
ships officially with Bareun 3.1.0.

## Resources

| Resource URI | Contents | Auth |
|---|---|---|
| `bareun://pos-tags` | The 47 POS tags (code · name · class) — same data as `list_pos_tags` | API key |
| `bareun://server-info` | Server metadata — name · version · build · active tools/resources | API key |
| `bareun://custom-dicts` | Names of custom-dictionary domains registered for the key | **valid** API key |

---

## Quick start

> **Tip — register globally.** Most tools default to *project* scope (the server is
> only available in one project). To use Bareun across **all** your projects, register
> it at **global / user** scope as shown below.

### Claude Code

```bash
# -s user → global: available in every project
claude mcp add -s user --transport http bareun https://api.bareun.ai/mcp \
  --header "api-key: YOUR_API_KEY"
```

Omit `-s user` for project-local scope. Check with `claude mcp get bareun`.

### Cursor

Global: `~/.cursor/mcp.json` · Project: `<project>/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "bareun": {
      "url": "https://api.bareun.ai/mcp",
      "headers": { "api-key": "YOUR_API_KEY" }
    }
  }
}
```

### VS Code

Global: run **MCP: Open User Configuration** · Project: `<project>/.vscode/mcp.json`

```json
{
  "servers": {
    "bareun": {
      "type": "http",
      "url": "https://api.bareun.ai/mcp",
      "headers": { "api-key": "YOUR_API_KEY" }
    }
  }
}
```

### Claude Desktop — `claude_desktop_config.json`

Claude Desktop bridges header-authenticated remote servers via `mcp-remote`
(Node.js required):

```json
{
  "mcpServers": {
    "bareun": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.bareun.ai/mcp",
        "--header", "api-key: YOUR_API_KEY"
      ]
    }
  }
}
```

### Cline — `cline_mcp_settings.json`

Open **MCP Servers → Configure MCP Servers** in Cline, then add:

```json
{
  "mcpServers": {
    "bareun": {
      "type": "streamableHttp",
      "url": "https://api.bareun.ai/mcp",
      "headers": { "api-key": "YOUR_API_KEY" },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

All five tools are read-only (`readOnlyHint`), so listing them in `autoApprove` is
safe if you would rather not confirm every call.

### ChatGPT — Developer Mode

ChatGPT talks to Streamable HTTP servers directly — no directory review needed.
Turn on **Developer mode** (Settings → Apps & Connectors → Advanced), then **Create**
a connector:

- **URL:** `https://api.bareun.ai/mcp`
- **Authentication:** **OAuth** — Bareun runs its own OAuth 2.1 (PKCE) endpoint, so
  ChatGPT opens a login page where you paste your Bareun API key. (ChatGPT's connector
  dialog offers OAuth or no-auth; if your build also lets you set request headers, an
  `api-key` header works just as well.)

Menu wording and plan availability shift between ChatGPT releases — Developer mode is
an account-level toggle, and on Business/Enterprise a workspace owner enables it first.

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

Set **Transport** to `Streamable HTTP`, **URL** to `https://api.bareun.ai/mcp`, and
add header `api-key: YOUR_API_KEY`.

---

## Example

```jsonc
// tools/call → analyze_syntax  (format: compact)
{ "text": "나는 학교에 간다.", "format": "compact" }
// → "나/NP 는/JX 학교/NNG 에/JKB 가/VV ㄴ다/EF ./SF"
```

## Links

- **Service:** https://bareun.ai
- **Docs:** https://bareun.ai/docs
- **MCP guide:** https://bareun.ai/docs/howtouse/mcp
- **API keys & usage:** https://bareun.ai/docs/howtouse/cloud-api

## License

The contents of this repository (documentation, registry manifests, examples) are
released under the [MIT License](./LICENSE). The Bareun engine itself is a
proprietary service operated by Baikal AI; access is governed by the bareun.ai
terms of service.