Content
# Tool List
> Korean Personal Information Anonymization Open-Source Engine — Rule-based Detection + Local LLM Contextual Judgment Hybrid
Korean **Python library + CLI + MCP Server** for detecting and anonymizing personal information (resident registration number, phone number, address, name, etc.) in Korean documents and datasets.
Aims to be a **privacy layer** that AI agents handling Korean data go through.
**2026 Open Source Developer Competition** (Ministry of Science and Technology Information and Communication Promotion Agency) entry — Team **maskingtape** · Apache-2.0
## Why maskingtape?
- **Korean-specific**: Resident registration number (including checksum verification), Korean phone number, road name address, Korean name, etc. — fills the gap that English tools (such as Presidio) cannot cover
- **Hybrid detection**: Regular expression and dictionary rules (fast, deterministic) + local LLM contextual judgment (for ambiguous cases such as distinguishing between people's names and business names, optional)
- **Completely local**: No external API calls. Only uses Ollama-based open-weight models — personal information does not go outside
- **Rule-only mode**: Works without LLM — can be used in low-spec environments
- **MCP Server**: Can be inserted as an anonymization layer in AI agent workflows
## Quick Start (in development — API may change)
```bash
git clone https://github.com/ChoHyeonChan/maskingtape.git
cd maskingtape
python -m venv .venv
# Windows: .venv\Scripts\activate / macOS·Linux: source .venv/bin/activate
pip install -e "packages/core[dev]"
maskingtape "주민번호 800101-1234560 문의주세요"
# → 주민번호 ************** 문의주세요
maskingtape --strategy label "연락처 010-1234-5678" # → 연락처 [전화번호]
maskingtape --scan "주민번호 800101-1234560 문의주세요" # only detection report (JSON)
pytest packages/core # test
```
Current detection: **Resident Registration Number** (checksum verification), **Phone Number** (mobile, landline, 070, +82 notation), **Email**, **Address** (administrative district), **Name** (rules + local LLM contextual judgment)
Using as a library:
```python
from maskingtape import Pipeline
result = Pipeline().anonymize("주민번호 800101-1234560 문의주세요")
print(result.text) # 주민번호 ************** 문의주세요
print(result.detections) # [Detection(kind='rrn', start=5, end=19, ...)]
```
※ The resident registration number in the example is a **synthetic number** that only matches the checksum.
## Accuracy (public benchmark)
Measures accuracy using its own **synthetic dataset** without copyright or personal information concerns — public benchmark is a key differentiator of this project. `python -m bench.evaluate bench/datasets/synth_v1.jsonl` actual measurement:
| Type | precision | recall | F1 |
|---|---|---|---|
| Resident Registration Number | 1.000 | 1.000 | 1.000 |
| Phone Number | 1.000 | 1.000 | 1.000 |
| Email | 1.000 | 1.000 | 1.000 |
| Address | 1.000 | 1.000 | 1.000 |
| Name (rules) | 0.890 | 0.847 | 0.868 |
| **Overall** | **0.961** | **0.943** | **0.952** |
Numbers and addresses are perfectly caught by pattern rules. Names require contextual judgment, which has limitations with rules only (F1 0.868), so **local LLM hybrid** is used to supplement — filters out false positives like "이용 안내" '이용' using context. (Measurement: `bench/` reference)
## Using as MCP Server (for AI Agents)
Automatically anonymizes data before sending it outside as a privacy layer for agents:
```bash
pip install -e packages/core -e packages/mcp-server
claude mcp add maskingtape -- maskingtape-mcp # Claude Code registration
```
Provided tools: `scan_text` (detection report), `anonymize_text` (mask/label anonymization), `anonymize_file` (anonymize local file and save a copy). Details: [packages/mcp-server](packages/mcp-server)
## Repository Structure
All detection and masking logic is in `packages/core` **only**, and the rest wraps around it — fixing the detector once improves all surfaces (CLI, MCP, API, app).
```mermaid
flowchart TD
core["packages/core: detection and masking engine"]
core --> cli["CLI: maskingtape command"]
core --> mcp["packages/mcp-server: MCP Server"]
core --> api["apps/api: REST API"]
api --> web["apps/web: web playground"]
api --> desktop["apps/desktop: desktop app"]
bench["bench: synthetic benchmark"] -.->|accuracy measurement| core
```
> Web and desktop use core CLI directly until integration.
| Path | Content | Responsible |
|---|---|---|
| `packages/core/` | Python detection and masking engine + CLI (pure logic) | Cho Hyeon Chan |
| `packages/mcp-server/` | MCP Server — exposes core as an agent tool | Cho Hyeon Chan |
| `apps/api/` | FastAPI backend — shared by web and desktop | Full stack |
| `apps/web/` | Web playground (detection highlight demo) | Front-end ×2 |
| `apps/desktop/` | Flutter desktop app (drag & drop batch processing) | Flutter |
| `bench/` | Synthetic benchmark data + F1 accuracy report | Data |
## Contributing
- **[CONTRIBUTING.md](CONTRIBUTING.md)** — collaboration rules (issue → branch → PR → merge). If working with AI, read this file first.
- **[ROADMAP.md](ROADMAP.md)** — development plan and current accuracy
- **[CLAUDE.md](CLAUDE.md)** — mandatory rules from competition regulations (team disqualification if violated)
- Progress: [Issues](https://github.com/ChoHyeonChan/maskingtape/issues) · [Milestones](https://github.com/ChoHyeonChan/maskingtape/milestones)
- When adding dependencies, update [SBOM.md](SBOM.md) in the same PR.
## License
[Apache-2.0](LICENSE). All dependencies' origins and licenses are recorded in [SBOM.md](SBOM.md).
