rypsok 0.2.0

Headless meta-search service for AI agents, served over the Model Context Protocol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# rypsok

[![CI](https://github.com/nabbisen/rypsok/actions/workflows/ci.yml/badge.svg)](https://github.com/nabbisen/rypsok/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/rypsok.svg)](https://crates.io/crates/rypsok)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**Headless meta-search for AI agents.** One tool call, several engines, one
clean answer, nothing leaked.

## Overview

rypsok is a small service that an AI agent runtime calls over the Model
Context Protocol (MCP). It queries several search engines at once, merges
and ranks their results, cleans every piece of external text before it
reaches the agent, and refuses to send anything that looks like a secret.
It is written in Rust and runs as one process with one configuration file.

Tools: `web_search` (0.1.0), `engine_status` (0.2.0), `web_fetch` (0.3.0).

## Why and when

- **Your agent needs the web, not a browser.** rypsok returns bounded,
  structured results sized for a context window, never a page dump.
- **You care where queries go.** Engines are admitted one by one with their
  terms on record; queries carrying credentials are refused; logs never hold
  a query or a URL path.
- **You want one dependency, not a stack.** One binary, stdio transport,
  no database, no browser engine.

rypsok is not a crawler, not a scraper by default, and not an answer engine:
it returns what the engines returned, cleaned and ranked, and says so.

## Quick start

```sh
cargo install rypsok
rypsok serve            # MCP over stdio, Wikipedia only, no file needed
```

Add an MCP server entry to your agent runtime, for example:

```json
{ "mcpServers": { "rypsok": { "command": "rypsok", "args": ["serve"] } } }
```

To add Brave Search, put a key in the environment and a file next to it:

```toml
# rypsok.toml
config_version = 1

[engines.brave]
type = "brave"
categories = ["general"]
api_key_env = "BRAVE_API_KEY"
```

```sh
rypsok check --config rypsok.toml   # validates and prints the effective settings
rypsok serve --config rypsok.toml
```

See [Getting started](docs/src/getting-started.md), the
[tools reference](docs/src/reference/tools.md) and the
[configuration reference](docs/src/reference/configuration.md).

## Design notes

- **Two crates.** `rypsok-core` holds every model, pipeline, driver and
  policy and depends on no protocol SDK; `rypsok` adds the MCP adapters and
  the command line. CI fails when a protocol crate reaches the core.
- **One structured response.** Every tool returns one outcome (`ok`,
  `partial`, `empty`) with notices from a fixed vocabulary; nothing is
  altered or reduced silently.
- **A content boundary.** External text is cleaned, bounded and stripped of
  invisible characters in one place; it is never rewritten.
- **Specification first.** Requirements, external design, limits and the
  threat register are baselined in `docs/src/maintainers/`; every test
  names the requirement it verifies.

## More detail

- [Documentation](docs/src/SUMMARY.md) (mdBook): getting started,
  tools and responses, configuration, integration guide.
- [Requirements](docs/src/maintainers/requirements.md) and
  [external design](docs/src/maintainers/external-design.md).
- [Roadmap](ROADMAP.md) and [RFCs](rfcs/README.md).
- [Changelog](CHANGELOG.md).

## License

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