Skip to content
Back to search

ccp

CCP, the Core Context Protocol: give your AI the core context it needs, nothing more. Token-efficient, read-only servers for databases, Redis, WebSocket, Socket.IO, CSV and REST APIs, for Claude and MCP clients.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hacimertgokhan--ccp/badge.svg)](/listings/hacimertgokhan--ccp)

HTML

<a href="/listings/hacimertgokhan--ccp"><img src="/api/listings/hacimertgokhan--ccp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. install the servers you need
cargo install --git https://github.com/hacimertgokhan/ccp mysql-ccp      # or any server in the table below

# 2. add one to Claude
claude mcp add shop \
  -e CCP_HOST=127.0.0.1 -e CCP_USER=readonly -e CCP_DBNAME=shop \
  -e CCP_PASSWORD="$DB_PASSWORD" \
  -- mysql-ccp

Claude gets two tools, `ccp_schema` (read once) and `ccp_query`. Ask it something about your data and it sends one compact query. More examples:

claude mcp add notes   -e CCP_PATH=/path/to/app.db                        -- sqlite-ccp
claude mcp add sales   -e CCP_PATH=/data/sales.csv                        -- csv-ccp
claude mcp add cache   -e CCP_HOST=127.0.0.1                              -- redis-ccp
claude mcp add trades  -e CCP_URL=wss://stream.example.com/trades         -- websocket-ccp
claude mcp add prices  -e CCP_URL=https://realtime.example.com            -- socketio-ccp
claude mcp add github  -e CCP_URL=https://api.github.com -e CCP_BEARER="$GITHUB_TOKEN" -- http-ccp

Want to look first? `cargo run -p ccp -- demo` shows a query and its byte cost with no setup at all.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 241 lines
  1. <div align="center">
  2. # CCP — Core Context Protocol
  3. **Give your AI the core context it needs. Nothing more.**
  4. [![CI](https://github.com/hacimertgokhan/ccp/actions/workflows/ci.yml/badge.svg)](https://github.com/hacimertgokhan/ccp/actions/workflows/ci.yml)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. ![Rust](https://img.shields.io/badge/built%20with-Rust-orange)
  7. [Quick start](#quick-start) · [Servers](#servers) · [How it works](#how-it-works) · [Benchmark](#benchmark) · [Build your own](#build-your-own-server) · [Protocol](docs/PROTOCOL.md) · [Contributing](CONTRIBUTING.md)
  8. </div>
  9. ---
  10. Most of what an AI agent reads is not what it needed: whole rows when it wanted two columns, a
  11. hundred calls where one would do, a firehose when it wanted a summary, a 2 MB file when it wanted a
  12. total. Context windows fill up, bills grow, answers slow down.
  13. **CCP is a small protocol built on one idea: a model should receive exactly the *core context* its
  14. question requires, from any data source, in one round trip.** It is not limited to databases: a
  15. cache, a live feed, an API, a CSV file and a report all speak the same compact language.
  16. ```text
  17. SQL users(id:7){name posts{title comments{body}}}
  18. Reports orders(group:"status",order:"-sum_total"){status count sum_total avg_total}
  19. Redis hashes(match:"user:*",limit:50){_key name email}
  20. WebSocket summary(wait:10,field:"sym"){count per_second values{value count}}
  21. CSV sales(group:"region"){region count sum_price}
  22. REST API get(path:"/users"){id name address.city}
  23. ```
  24. One request each. Only the fields you named. Related data nested. Aggregates computed *in the
  25. server*, so a 13 MB file, a 600-message window or a 144 KB API response costs the model a few hundred bytes.
  26. ## Why CCP
  27. | | |
  28. |---|---|
  29. | **Ask for what you need** | Fields are chosen per request; results carry no unused data. |
  30. | **Compute where the data is** | Filters, ordering, grouping and aggregates run in the server; the model gets the report, not the rows. |
  31. | **One call, not N+1** | Relations nest (`users{posts{comments{...}}}`); Redis reads are pipelined; stream windows are summarised. |
  32. | **Read the vocabulary once** | The schema is advertised a single time, not repeated per call. |
  33. | **Compact on the wire** | No quoted keys, no per-call envelope: fewer bytes, fewer tokens. |
  34. | **Light and fast** | Small native binaries (0.5–2 MB), single-digit-millisecond start-up, µs–ms queries, flat memory. |
  35. | **Safe by construction** | Read-only, bounded, caller text is never syntax (bound parameters, fixed command sets, fixed base URLs). |
  36. | **Drop-in for Claude** | Every CCP server is also a standard MCP server: one command to install. |
  37. ## Quick start
  38. ```bash
  39. # 1. install the servers you need
  40. cargo install --git https://github.com/hacimertgokhan/ccp mysql-ccp # or any server in the table below
  41. # 2. add one to Claude
  42. claude mcp add shop \
  43. -e CCP_HOST=127.0.0.1 -e CCP_USER=readonly -e CCP_DBNAME=shop \
  44. -e CCP_PASSWORD="$DB_PASSWORD" \
  45. -- mysql-ccp
  46. ```
  47. Claude gets two tools, `ccp_schema` (read once) and `ccp_query`. Ask it something about your data and
  48. it sends one compact query. More examples:
  49. ```bash
  50. claude mcp add notes -e CCP_PATH=/path/to/app.db -- sqlite-ccp
  51. claude mcp add sales -e CCP_PATH=/data/sales.csv -- csv-ccp
  52. claude mcp add cache -e CCP_HOST=127.0.0.1 -- redis-ccp
  53. claude mcp add trades -e CCP_URL=wss://stream.example.com/trades -- websocket-ccp
  54. claude mcp add prices -e CCP_URL=https://realtime.example.com -- socketio-ccp
  55. claude mcp add github -e CCP_URL=https://api.github.com -e CCP_BEARER="$GITHUB_TOKEN" -- http-ccp
  56. ```
  57. Want to look first? `cargo run -p ccp -- demo` shows a query and its byte cost with no setup at all.
  58. ## Servers
  59. All servers live in [`plugins/`](plugins).
  60. | Server | Source | Good for | Config |
  61. |---|---|---|---|
  62. | [`mysql-ccp`](plugins/mysql-ccp) | MySQL, MariaDB | tables, relations, reports | `CCP_HOST` `CCP_USER` `CCP_PASSWORD` `CCP_DBNAME` `CCP_PORT` |
  63. | [`postgres-ccp`](plugins/postgres-ccp) | PostgreSQL | tables, relations, reports | same |
  64. | [`sqlite-ccp`](plugins/sqlite-ccp) | SQLite file | app databases, local data | `CCP_PATH` |
  65. | [`csv-ccp`](plugins/csv-ccp) | CSV / TSV files | **reporting** over files too big to read | `CCP_PATH` |
  66. | [`redis-ccp`](plugins/redis-ccp) | Redis | keys, hashes as table rows, lists, sets, zsets, streams, INFO | `CCP_HOST` `CCP_PASSWORD` … |
  67. | [`websocket-ccp`](plugins/websocket-ccp) | WebSocket feeds | live data: latest messages, windows, summaries | `CCP_URL` `CCP_BEARER` `CCP_SUBSCRIBE` |
  68. | [`socketio-ccp`](plugins/socketio-ccp) | Socket.IO | events by name, windows, summaries | `CCP_URL` `CCP_AUTH` `CCP_EMIT` `CCP_EVENTS` |
  69. | [`http-ccp`](plugins/http-ccp) | any REST / JSON API | trimming bloated responses to the fields you need | `CCP_URL` `CCP_BEARER` `CCP_HEADERS` |
  70. **Something else?** Kafka, MQTT, MongoDB, a log file, an internal service: a server is about 100–150
  71. lines. See [Build your own server](#build-your-own-server).
  72. ## How it works
  73. ```text
  74. ┌────────┐ MCP (stdio) ┌──────────────┐ native protocol ┌─────────────┐
  75. │ Claude │ ───────────────▶ │ *-ccp │ ───────────────────▶ │ data source │
  76. └────────┘ ccp_query(...) │ server │ ◀─────────────────── └─────────────┘
  77. └──────────────┘
  78. ```
  79. 1. The server learns the source's shape: a database catalog, a Redis key space, a stream's
  80. fields, a file's columns.
  81. 2. It advertises a small **schema** the model reads once (SQL example):
  82. ```text
  83. root users(id:Int,name:Str,city:Str):[Users]
  84. type Users{id:Int,name:Str,city:Str,posts:[Posts]}
  85. all table roots also take limit:Int,offset:Int,order:"-f,g",group:"cols"; with group the braces take count,sum_C,...
  86. ```
  87. 3. Each question becomes **one query**. Only requested fields are fetched; nested relations load in
  88. batches; aggregates run inside the source; stream windows wait server-side.
  89. 4. The answer is encoded **compactly** and returned.
  90. ```text
  91. users{id name} list (limit 100), two fields
  92. users(id:7){name email} filter by column
  93. users(city:"Tokyo",order:"-id",limit:5) filter + sort + page
  94. posts(limit:20){title author{name}} follow a foreign key
  95. orders(group:"channel,status"){channel status count sum_total} a report
  96. messages(wait:5,limit:20,event:"trade"){px symbol} wait for new events
  97. ```
  98. Full grammar, wire format and per-server vocabulary: [docs/PROTOCOL.md](docs/PROTOCOL.md).
  99. ## Benchmark
  100. Real CCP servers, driven over MCP exactly as Claude drives them, against the conventional tool for each
  101. source, on the same data: MariaDB 11 / PostgreSQL 17 / SQLite, Redis 7, a live WebSocket and Socket.IO
  102. feed, a 200,000-row CSV, a REST API. Bytes include JSON-RPC envelopes; tokens are estimated as bytes/4
  103. on both sides. Reproduce everything with `python3 bench/run_all.py` (method and baselines in
  104. [bench/README.md](bench/README.md), every table in [bench/RESULTS.md](bench/RESULTS.md)).
  105. ![Bytes the model reads per task](docs/benchmark.svg)
  106. | Source / task | CCP | Conventional tool | ≈Tokens (CCP → conventional) | Calls |
  107. |---|---:|---:|---:|---:|
  108. | SQL: a 7-question agent session | 8.8 KB | 11.4 KB careful · 738 KB naive | 2.2k → 2.9k · 189k | 9 vs 15 · 18 |
  109. | Redis: 50 hashes, 2 fields each | 3.6 KB | 13.4 KB | 0.9k → 3.4k | **1 vs 51** |
  110. | WebSocket: report on a 3 s window | 457 B | 165.8 KB | 115 → 42.4k | 1 vs 1 |
  111. | Socket.IO: report on a 3 s window | 472 B | 141.0 KB | 118 → 36.1k | 1 vs 1 |
  112. | CSV: revenue by region, 200k rows | 598 B | 13.1 MB | 150 → 3.4M | 1 vs 1 |
  113. | REST API: 100 users, 2 fields | 2.7 KB | 140.9 KB | 0.7k → 36.1k | 1 vs 1 |
  114. **Token spend.** In an SQL agent session CCP uses **24% fewer tokens than a careful baseline** (exact
  115. columns, JOINs) and **99% fewer than a naive one** (`SELECT *`); at an illustrative $3 per million input
  116. tokens that is $6.56 vs $8.76 vs $566.92 per 1,000 sessions. Reports are where it matters most: "revenue by
  117. status over 5,000 orders" is 587 B against 478 KB of rows. Streams and files are not even comparable:
  118. the raw alternative does not fit a context window.
  119. **Speed.** One pipelined Redis call took 0.6 ms against 8.8 ms for 50 sequential commands on localhost,
  120. and the gap grows with the network: at 10 ms RTT, 21 ms against 519 ms. The reader ingests **~175,000
  121. WebSocket/Socket.IO messages per second** on one core (bound by the test feeder, so a lower bound) at
  122. ≈0.2 µs/message of CPU for WebSocket, and queries over a full buffer return in 30 µs to 0.5 ms. Going
  123. through CCP to an HTTP API adds no measurable overhead (0.21 ms vs 0.19 ms bare).
  124. **Footprint.** Release binaries are 0.5–2.2 MB; start-up is 10 ms (4 ms for Redis; PostgreSQL 41 ms
  125. including introspection); idle memory is 2–7 MB per server. `csv-ccp` loads 13 MB / 200k rows in 0.7 s
  126. into 24 MB of RAM and answers a group-by over all rows in ~60 ms.
  127. | Server | Binary | Cold start | RSS | Typical query p50 / p95 |
  128. |---|---:|---:|---:|---:|
  129. | sqlite-ccp | 2.2 MB | 10 ms | 6 MB | 0.73 / 1.64 ms |
  130. | mysql-ccp | 2.1 MB | 18 ms | 4 MB | 0.77 / 0.99 ms |
  131. | postgres-ccp | 1.2 MB | 41 ms | 7 MB | 2.02 / 3.44 ms |
  132. | redis-ccp | 0.5 MB | 10 ms | 2 MB | 0.23 / 0.33 ms |
  133. | websocket-ccp | 1.6 MB | 10 ms | 7 MB | 0.03 / 0.06 ms |
  134. | socketio-ccp | 1.7 MB | 10 ms | 7 MB | 0.03 / 0.03 ms |
  135. | csv-ccp | 2.2 MB | 708 ms (loads the file) | 24 MB | 62.9 / 74.8 ms (group-by over 200k rows) |
  136. | http-ccp | 1.8 MB | 10 ms | 5 MB | 0.21 / 0.25 ms |
  137. **Where CCP does not win**, shown in the full results rather than hidden: a careful model that always
  138. names columns and writes JOINs closes much of the SQL gap (CCP is still 0–29% smaller per task, with
  139. fewer calls); a Redis leaderboard costs *more* with CCP (objects use more bytes than a flat array);
  140. and the Socket.IO server was verified against a protocol-faithful Engine.IO v4 mock, not yet against
  141. a real Socket.IO server. The three SQL servers return byte-identical output for the same 12 queries
  142. (filters, relations, aggregates, ordering).
  143. ## Security
  144. * **Read-only**: sessions open read-only; only `SELECT` and read commands are ever generated.
  145. * **Caller text is data, never syntax**: SQL identifiers come from the database catalog and every value is
  146. a bound parameter; Redis uses a fixed command set with binary-safe arguments; `http-ccp` joins a
  147. validated path to a fixed base URL and never follows redirects.
  148. * **The model cannot send**: anything a stream server transmits (a subscribe message, an emitted
  149. event) is configured by *you* through environment variables.
  150. * **Bounded**: rows, relation rows, nesting, scan calls, buffer size, response size and file size are all capped.
  151. * **No secrets in output**: credentials are scrubbed from error messages.
  152. * Use dedicated read-only credentials anyway. Connections are plain TCP for now (TLS for MySQL,
  153. PostgreSQL and Redis is on the [roadmap](#roadmap); `wss://` and `https://` are supported): use
  154. localhost, a tunnel or a private network.
  155. Report vulnerabilities privately: see [SECURITY.md](SECURITY.md).
  156. ## Build your own server
  157. CCP servers are small because the shared crates do the heavy lifting. Pick the closest starting point:
  158. | Your source | Build on | You write |
  159. |---|---|---|
  160. | A SQL database | `ccp-sql` | a connection, catalog introspection and one `select` (≈150 lines); relations, reports and paging come free |
  161. | A live feed | `ccp-stream` | the reader loop; buffering, `messages`/`summary`/`status`, reconnection come free |
  162. | JSON from anywhere | `ccp-mcp` | the fetch; field projection and the MCP server come free |
  163. | Anything else | `ccp-proto` | a `RootResolver` |
  164. Step-by-step with code: [docs/writing-a-server.md](docs/writing-a-server.md).
  165. ## Repository layout
  166. ```text
  167. crates/
  168. ccp-proto/ the protocol: parser, executor, compact encoding (zero dependencies)
  169. ccp-mcp/ runtime for every server: MCP front end, raw CCP mode, JSON projector
  170. ccp-sql/ SQL engine: catalog, relations, reports, safe SQL generation
  171. ccp-stream/ event-stream core: reader, ring buffer, messages / summary / status
  172. ccp/ demo CLI
  173. plugins/ ready-to-use servers (one crate each)
  174. mysql-ccp postgres-ccp sqlite-ccp csv-ccp redis-ccp websocket-ccp socketio-ccp http-ccp
  175. docs/ protocol spec, server-writing guide
  176. bench/ reproducible benchmark suite
  177. ```
  178. ## Roadmap
  179. - [ ] TLS for MySQL, PostgreSQL and Redis connections
  180. - [ ] Nested arguments (`posts(limit:3)` inside a query) and `having`
  181. - [ ] More servers: Kafka, MQTT, MongoDB, log files, gRPC
  182. - [ ] Prebuilt release binaries and a Homebrew tap
  183. - [ ] Verification of `socketio-ccp` against a real Socket.IO server in CI
  184. Ideas welcome: open an [issue](https://github.com/hacimertgokhan/ccp/issues/new/choose).
  185. ## Contributing
  186. Contributions are very welcome, new servers above all. Start with [CONTRIBUTING.md](CONTRIBUTING.md)
  187. and [Build your own server](docs/writing-a-server.md). Good first issues are labelled `good first issue`.
  188. ## License
  189. [MIT](LICENSE) © 2026 Hacı Mert Gökhan

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.