Metadata-Version: 2.4
Name: kura-mcp
Version: 0.2.0
Summary: Tool intelligence for AI agents. Analyze, optimize, and harmonize MCP tool descriptions and OpenClaw skills.
Project-URL: Homepage, https://github.com/getkura/kura
Project-URL: Repository, https://github.com/getkura/kura
Project-URL: Issues, https://github.com/getkura/kura/issues
Author: Grigory Sapunov
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,llm,mcp,openclaw,tool-selection
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tiktoken>=0.5
Provides-Extra: all
Requires-Dist: anthropic>=0.30; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: hnswlib>=0.7; extra == 'all'
Requires-Dist: matplotlib>=3.5; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: numpy>=1.24; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: sentence-transformers>=2.0; extra == 'all'
Requires-Dist: spacy>=3.0; extra == 'all'
Provides-Extra: analysis
Requires-Dist: hnswlib>=0.7; extra == 'analysis'
Requires-Dist: matplotlib>=3.5; extra == 'analysis'
Requires-Dist: numpy>=1.24; extra == 'analysis'
Requires-Dist: pandas>=2.0; extra == 'analysis'
Requires-Dist: sentence-transformers>=2.0; extra == 'analysis'
Requires-Dist: spacy>=3.0; extra == 'analysis'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: dump
Requires-Dist: mcp>=1.0; extra == 'dump'
Provides-Extra: suggest
Requires-Dist: anthropic>=0.30; extra == 'suggest'
Requires-Dist: google-genai>=1.0; extra == 'suggest'
Requires-Dist: openai>=1.0; extra == 'suggest'
Description-Content-Type: text/markdown

# 🔍 Kura

**Tool intelligence for AI agents.** Analyze, optimize, and harmonize MCP tool descriptions and OpenClaw skills.

Your agents connect to dozens of MCP tools and skills. Their descriptions are inconsistent, conflicting, and unoptimized. The result: wrong tool selection, wasted tokens, unreliable agent behavior.

Kura fixes this.

```bash
pip install kura-mcp
kura scan path/to/mcp-config.json
```

## What it does

**Detects conflicts** — finds tools with overlapping descriptions that confuse your agent's tool selection.

**Scores quality** — rates every tool description 0-100 and tells you exactly what to fix.

**Estimates token waste** — shows how much of your token budget goes to tool descriptions and where to cut.

**Suggests improvements** — optionally uses an LLM to rewrite vague descriptions into precise ones.

## Example

```
$ kura scan ~/.config/claude/claude_desktop_config.json

  🔍 Kura — Tool Quality Report

  Scanned: 47 tools across 8 MCP servers
  Overall catalog health: 64/100

  ── HIGH CONFLICTS ──────────────────────────────────

  ⚠ github/create_issue ↔ jira/create_ticket  (0.92)
    Both describe creating issues/tickets with title and description.

  ⚠ filesystem/search ↔ browser/find  (0.87)
    Both describe searching/finding with patterns.

  ── QUALITY ISSUES ──────────────────────────────────

  ✗ filesystem/search  (23/100)
    • Description too vague: "Search for files"
    • No parameter descriptions

  ── TOKEN BUDGET ────────────────────────────────────

  Total catalog: 18,400 tokens
  Estimated after optimization: ~7,200 tokens (-61%)
```

## Install

```bash
# Core (quality scoring + token estimation)
pip install kura-mcp

# With semantic similarity detection + NLP verb detection
pip install kura-mcp[analysis]

# With live MCP server connections + OAuth
pip install kura-mcp[dump]

# With LLM-enhanced scoring (Anthropic, OpenAI, or Google Gemini)
pip install kura-mcp[suggest]

# Everything
pip install kura-mcp[all]
```

## Usage

```bash
# Scan a tools JSON file
kura scan tools.json

# Scan an OpenClaw skills directory
kura scan ~/.openclaw/skills/

# JSON output for CI/CD
kura scan tools.json --format json

# Custom similarity threshold
kura scan tools.json --threshold 0.80

# Skip similarity analysis (faster, no model download)
kura scan tools.json --no-similarity

# Approximate similarity + cached embeddings for large catalogs
kura scan big-catalog/ --ann

# Write full run artifacts (JSON, CSV, markdown, PNG charts)
kura scan tools.json --run-dir runs/analysis-2026-04/

# Dump tools from running MCP servers (auto-detects Claude Desktop + Cursor)
kura dump -o tools.json
kura dump --list                    # show available servers
kura dump -s github -s slack        # dump specific servers
kura dump -i                        # ask before each server

# Then scan the dump
kura scan tools.json

# LLM-enhanced scoring (uses your own API key)
ANTHROPIC_API_KEY=sk-... kura scan tools.json --llm
kura scan tools.json --llm --model openai
kura scan tools.json --llm --model google
```

## Supported formats

- **Live MCP servers** via `kura dump` (stdio, HTTP, SSE — with OAuth support)
- **Claude Desktop** config (`claude_desktop_config.json`)
- **Cursor** config (`~/.cursor/mcp.json`)
- **OpenClaw** skill directories (`SKILL.md` files)
- **Generic MCP** tool list JSON (any `tools/list` output)

## Why "Kura"?

Kura means "curate" — because tool quality is a curation problem, not a configuration problem. Your agents are only as good as the tools they can find.

## Roadmap

- [x] CLI quality scanner
- [x] Semantic conflict detection across servers
- [x] OpenClaw skill directory scanning
- [x] Live MCP server dumping with OAuth
- [x] LLM-enhanced quality scoring (Anthropic, OpenAI, Gemini)
- [ ] CI/CD integration (GitHub Action)
- [ ] LLM-powered rewrite suggestions

See [issues](https://github.com/getkura/kura/issues) for what's next.

## License

MIT
