Metadata-Version: 2.4
Name: ladon-nous
Version: 0.1.0
Summary: MCP server exposing Ladon crawl data to AI agents (Claude Desktop, Cursor, etc.).
Author-email: Alessio Pascucci <feeder81@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/MoonyFringers/ladon-nous
Project-URL: Repository, https://github.com/MoonyFringers/ladon-nous
Project-URL: Framework, https://github.com/MoonyFringers/ladon
Project-URL: Issues, https://github.com/MoonyFringers/ladon-nous/issues
Project-URL: Documentation, https://moonyfringers.github.io/ladon
Keywords: mcp,model-context-protocol,ladon,ladon-adapter,crawler,ai-agent,claude,duckdb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=3.3.0
Requires-Dist: duckdb>=1.0.0
Requires-Dist: pytz>=2023.3
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# ladon-nous

**MCP server exposing Ladon crawl data to AI agents.**

`ladon-nous` (νοῦς — the Greek principle of divine intellect) is the mind interface
of the [Ladon](https://github.com/MoonyFringers/ladon) crawler framework. It serves
crawled data from a DuckDB database over the
[Model Context Protocol](https://modelcontextprotocol.io/) (MCP), making it
available to Claude Desktop, Cursor, and other MCP-compatible AI clients.

---

## What it does

Point `ladon-nous` at a DuckDB file produced by a Ladon adapter (e.g.
[ladon-mimir](https://github.com/MoonyFringers/ladon-mimir)), and your AI client
can instantly:

- **Search articles** by keyword across title, summary, and full text
- **List crawl runs** and check their status
- **Read full article content** as a resource

---

## Tools

| Tool | Description |
|---|---|
| `article_search(query, limit=10)` | Keyword search across crawled articles |
| `run_list(limit=20)` | Recent crawl runs with status and article counts |
| `crawl_status(run_id)` | Status detail for a specific run |

## Resources

| Resource | Description |
|---|---|
| `ladon://articles/{page_id}` | Full Markdown content of a single article |

---

## Installation

```bash
pip install ladon-nous
```

Or for development:

```bash
git clone https://github.com/MoonyFringers/ladon-nous
cd ladon-nous
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

---

## Usage

```bash
ladon-nous serve --db /path/to/mimir.db
```

The server speaks MCP over `stdio` by default (compatible with Claude Desktop).
Add `--transport sse` for HTTP/SSE deployment.

---

## Claude Desktop setup

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ladon-nous": {
      "command": "/path/to/.venv/bin/ladon-nous",
      "args": ["serve", "--db", "/path/to/mimir.db"]
    }
  }
}
```

Restart Claude Desktop. The `article_search`, `run_list`, and `crawl_status`
tools will appear automatically.

---

## Compatibility

`ladon-nous` v0.1.0 is designed for databases produced by
[ladon-mimir](https://github.com/MoonyFringers/ladon-mimir) (Wikipedia adapter).
Support for other Ladon adapters will be added in v0.2.0 via the
`LadonMCPAdapter` plugin protocol.

---

## License

Apache-2.0. See [LICENSE](LICENSE).
