@rak-ad/mcp - npm Package Compare versions

Comparing version 0.1.0 to 0.2.0

CHANGELOG.md

+# Changelog
+
+All notable changes to `@rak-ad/mcp` and the RAK OS public surface. Format: [Keep a Changelog](https://keepachangelog.com); versioning follows the npm package.
+
+## [0.2.0] — 2026-07-15
+
+### Added
+- **RAK OS** identity: `MANIFESTO.md` (+PL), `REALM.md` (roles, levels L0–L5 incl. Node Sovereign, economic phases, absorption-proofing), full governance + community scaffolding.
+- **Skills**: `owned` (content wallet), `discovery` (meta), `rag` (split out as a free-tier skill), skills index, `RFC 0001` (irc/talk).
+- **Shared format**: `SPEC.md` v0.2 base envelope (`kind`/`ext`/wallet/interop) + `docs/profiles/fop.md` mapping POXI-FOP — one language for content and market.
+- **Automatic orchestra**: skill-lint, honesty-lint, link-check, smoke, welcome, stale, realm-ledger, release-drafter workflows + supporting scripts.
+- **Client resilience**: `bin/rak-mcp.js` retries transient startup failures with backoff.
+- `ROADMAP.md`, `docs/maintenance.md`, `.gitattributes`.
+
+### Changed
+- README rebranded to RAK OS; added "Who's behind this", "Build your own RAK", "Built on Open Mercato".
+- `research` skill: RAG tools moved to their own free-tier `rag` skill (were mislabeled paid).
+- English-ized `bin/` comments; fixed `RAK-MCP` → `rak-mcp` casing in `SPEC.md`.
+
+### Removed
+- Internal-only `MCP-PRODUCT-SYNC.md` (leaked internal references; preserved privately).
+
+## [0.1.0] — 2026-07
+
+### Added
+- Initial public surface: `@rak-ad/mcp` stdio↔remote bridge, `SPEC.md` (RAK content language v0.1), `ECONOMICS.md`, six skill cards, MCP registry manifests.

skills/discovery.md

+# SKILL: rak-discovery — meta / discovery (the free index)
+
+## When to use
+When an agent needs to **discover** RAK before (or without) reading: the census of local sources, the catalog of tools/skills and their tiers, pipeline health/freshness, and the catalog of agents built on RAK. This is the anonymous AEO surface — **no key required**.
+
+## Tools
+| Tool | Purpose | Tier |
+|---|---|---|
+| `rak_meta_list_sources` | census of 1709 PL local sources; filter by `voivodeship`/`type` (`limit?`, `offset?`) | anon (no key) |
+| `rak_meta_list_skills` | catalog of `rak_<module>_<op>` tools + skill catalog, with required tier & scope | anon (no key) |
+| `rak_meta_health` | pipeline status & freshness (latest publish, 24h volume, enabled sources) | anon (no key) |
+| `rak_meta_list_agents` | catalog of active agents built on RAK (reference Stanowski + community agents) | anon (no key) |
+
+## Tier / cost
+Anonymous / discovery — available on every tier including `anon`. No credit cost; results are cached (near-static).
+
+## Build on RAK
+`rak_meta_list_agents` returns the scaffold and SDK for building your own:
+- `npx create-rak-agent <name>` — scaffold an agent that speaks `rak_*`.
+- SDK / spec: this repository ([`SPEC.md`](../SPEC.md)). Ship an agent or a national node and it becomes discoverable here (see **Node Sovereign** in [`REALM.md`](../REALM.md)).
+
+## Example prompts
+- "List RAK sources in Lesser Poland, then check pipeline freshness."
+- "What RAK tools are free for readers vs paid for subscribers?"
+- "Show the agents built on RAK and how I'd scaffold my own."

skills/owned.md

+# SKILL: rak-owned — owned content lane (the content wallet)
+
+## When to use
+When a creator publishes their own work as an **owned content object** and reads it back — the loop that makes content *owned → citable → monetizable* ([`SPEC.md §4`](../SPEC.md), [`ECONOMICS.md`](../ECONOMICS.md)). Content lands in the creator's **own band** (`creator:<id>`), never in the wire or the portal. The band is derived server-side from the API key's `subscriber_user_id` — you cannot publish into someone else's band.
+
+## Tools
+| Tool | Purpose | Tier |
+|---|---|---|
+| `rak_owned_publish` | publish an artifact (e.g. from `rak_write_draft`) as an owned object with a license → `{slug, license, namespace, provenance}` | paid (creator) |
+| `rak_owned_list` | list your owned objects (`limit?`, `status?` = published/draft/scheduled/all) | paid (creator) |
+| `rak_owned_get` | one owned object by `slug`, with provenance verification attached | paid (creator) |
+| `rak_owned_verify` | verify provenance on-demand by `slug` or `id`: signature valid + content unmodified (tamper-evidence) | paid (creator) |
+
+## Tier / cost
+`paid`+ tier with the `skills:action` scope (publish) or `content:read` (list/get/verify). No credit cost — provenance signing is free compute. Requires a key bound to a creator account.
+
+## Provenance (the content wallet)
+Each published object is signed over `hash(title + content)`. `rak_owned_get`/`verify` recompute the hash and check the signature: a tampered object returns `unmodified: false`. Signing is best-effort and never blocks publishing. License defaults to `owned_public` (free to read **and cite** — this is what drives AEO and, later, pay-per-citation).
+
+## Don't
+- Don't confuse `rak_owned_publish` (your own band, creator-owned) with `rak_write_publish` (the RAK portal, internal tier).
+- Don't treat `owned_public` as private — it is public and citable by design; use `owned_licensed`/`restricted` otherwise.
+
+## Example prompts
+- "Publish my draft as an owned public article and show its slug + provenance."
+- "List my owned articles, then verify the newest one hasn't been modified."

skills/rag.md

+# SKILL: rak-rag — retrieval over the RAK archive (free reader)
+
+## When to use
+When an agent needs semantic retrieval over the RAK archive: articles related to a query or to a specific article, and dense vector search. **Free reader tier** — every result carries a canonical `rak.ad` URL so it is directly citable (AEO).
+
+## Tools
+| Tool | Purpose | Tier |
+|---|---|---|
+| `rak_rag_find_related` | related articles to a `query` **or** to an article (`slug`); `count?` (default 6), `section?` | free (reader) |
+| `rak_rag_semantic_search` | hybrid dense + FTS search over article embeddings; `query`, `matchCount?` (default 10), `section?` | free (reader) |
+
+## Tier / cost
+`free` reader tier (available from `anon`), `content:read` scope, no credit cost. The tiny embedding cost is absorbed; both tools are rate-limited and cached. `semantic_search` falls back to sparse FTS if the embedding provider is down, so it returns results instead of an empty set.
+
+## Notes
+- Results include an absolute canonical `rak.ad` URL, `similarity`, section and excerpt — ready to cite.
+- For fresh listings/feeds use [`content`](./content.md); for web + external research use [`research`](./research.md).
+
+## Example prompts
+- "Find 6 RAK articles related to the spatial-planning reform."
+- "Semantic-search the RAK archive for coverage of the local budget in Silesia."

skills/README.md

+# RAK OS skills
+
+Each skill is a card describing a family of `rak_<module>_<op>` tools: when to use it, the tools, the tier, and example prompts. Tools are spoken over MCP against the RAK node ([`../SPEC.md §6`](../SPEC.md)); the authoritative tier/scope matrix lives in the node's policy engine and is echoed by `rak_meta_list_skills`.
+
+| Skill | Module(s) | Tier | What it does |
+|---|---|---|---|
+| [content](./content.md) | `content` | free (reader) | Articles, wire feed, per-region feeds, hybrid search. |
+| [rag](./rag.md) | `rag` | free (reader) | Semantic retrieval over the RAK archive; citable URLs. |
+| [discovery](./discovery.md) | `meta` | anon (no key) | Source census, skills/agents catalog, health. The free index. |
+| [research](./research.md) | `research` | anon → paid | Web search, fact packs, summaries, URL → markdown. |
+| [write](./write.md) | `write` | paid → internal | Draft → plan → pipeline → publish. |
+| [media](./media.md) | `media` | paid | Image / video / TTS generation. |
+| [qa](./qa.md) | `qa` | paid | Fact-check, moderation, uniqueness. |
+| [owned](./owned.md) | `owned` | paid (creator) | Publish + read + verify your own content objects (the content wallet). |
+| [distribution](./distribution.md) | `crawl`, `distribution` | internal | Source harvesting + external publishing. |
+
+## Tiers
+
+`anon` (no key) → `free` (key, higher limits) → `paid` (subscriber; creation/media/qa/owned) → `partner` (read-only) → `internal` (publishing/distribution). Reader tools (content, rag, discovery) work anonymously — the growth engine.
+
+## Roadmap
+
+- **IRC / talk skill** — a chat surface for agents and people around content is proposed but not yet part of the MCP. See [`../docs/rfcs/0001-irc-skill.md`](../docs/rfcs/0001-irc-skill.md).

bin/rak-mcp.js

 #!/usr/bin/env node
 /**
- * @rak-ad/mcp — zero-config bridge do hostowanego RAK MCP (remote streamable-HTTP).
+ * @rak-ad/mcp — zero-config bridge to the hosted RAK MCP (remote streamable-HTTP).
  *
- * Klienty stdio-only (które nie umieją remote MCP) odpalają `npx -y @rak-ad/mcp`; ten wrapper
- * proxuje stdio ↔ https://rak.ad/api/mcp/rak/mcp przez `mcp-remote`. Klienty z natywnym remote
- * MCP (Claude Code, Cursor) mogą pominąć paczkę i wpiąć URL bezpośrednio.
+ * stdio-only clients (that can't speak remote MCP) run `npx -y @rak-ad/mcp`; this wrapper
+ * proxies stdio <-> https://rak.ad/api/mcp/rak/mcp via `mcp-remote`. Clients with native remote
+ * MCP (Claude Code, Cursor) can skip the package and wire the URL directly.
  *
  * ENV:
- *   RAK_API_KEY   — klucz `rk_…` (bez niego = darmowy/anonimowy tier, 13 narzędzi read/research).
- *   RAK_BASE_URL  — opcjonalnie nadpisz host (domyślnie https://rak.ad).
+ *   RAK_API_KEY   — an `rk_…` key (without it = free/anonymous tier: read + capped research tools).
+ *   RAK_BASE_URL  — optionally override the host (default https://rak.ad).
  */
@@ -22,10 +22,33 @@ import { spawn } from "node:child_process"
 
-const child = spawn("npx", args, {
-  stdio: "inherit",
-  shell: process.platform === "win32",
-})
-child.on("exit", (code) => process.exit(code == null ? 0 : code))
-child.on("error", (err) => {
-  console.error("[@rak-ad/mcp] nie udało się uruchomić mcp-remote:", err.message)
-  process.exit(1)
-})
+// Autohealing: transient network/DNS blips at launch can make mcp-remote exit
+// immediately. Retry only *fast* startup failures (ran < 5s, non-zero exit), with
+// backoff, up to a small cap. A clean exit (code 0) or a long-running session that
+// ends is passed through untouched — we never hot-loop and never retry a real close.
+const MAX_FAST_RETRIES = 3
+let fastFailures = 0
+
+function start() {
+  const startedAt = Date.now()
+  const child = spawn("npx", args, {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  })
+  child.on("exit", (code) => {
+    if (code === 0 || code == null) process.exit(0)
+    const ranMs = Date.now() - startedAt
+    if (ranMs < 5000 && fastFailures < MAX_FAST_RETRIES) {
+      fastFailures += 1
+      const backoff = 1000 * 2 ** (fastFailures - 1)
+      console.error(`[@rak-ad/mcp] startup failed (exit ${code}); retry ${fastFailures}/${MAX_FAST_RETRIES} in ${backoff}ms…`)
+      setTimeout(start, backoff)
+      return
+    }
+    process.exit(code)
+  })
+  child.on("error", (err) => {
+    console.error("[@rak-ad/mcp] failed to start mcp-remote:", err.message)
+    process.exit(1)
+  })
+}
+
+start()

package.json

 {
   "name": "@rak-ad/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "RAK Model Context Protocol — Polish local content (articles, wire, per-region feeds, 1709 sources) + AI editorial tools (research, writing, media, QA) for agents.",
   "type": "module",
   "bin": { "rak-mcp": "bin/rak-mcp.js" },
-  "files": ["bin", "skills", "README.md", "LICENSE"],
+  "files": ["bin", "skills", "README.md", "LICENSE", "CHANGELOG.md"],
   "engines": { "node": ">=18" },
@@ -9,0 +9,0 @@ "dependencies": { "mcp-remote": "^0.1.0" },

README.md

@@ -1,8 +0,10 @@
-# RAK MCP — Polish local news & data about Poland, for AI agents
+# RAK OS — media without an owner · Polish local news & data for AI agents
 
-> **RAK MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents instant access to Polish local content — 1709 sources, 16 regions, hybrid RAG and a wire feed, 24/7.** Free for readers, paid editorial RAK tools for subscribers.
+> **RAK OS is an open content language for the agentic web + a free reference stack.** RAK MCP — the `@rak-ad/mcp` [Model Context Protocol](https://modelcontextprotocol.io) server — gives AI agents instant access to Polish local content: 1709 sources, 16 regions, hybrid RAG and a wire feed, 24/7. Free for readers, paid editorial tools for subscribers.
 >
+> 🕊️ **Manifesto:** [`MANIFESTO.md`](./MANIFESTO.md) ([PL](./MANIFESTO.pl.md)) · 👑 **The Realm:** [`REALM.md`](./REALM.md) · 🏛️ **Governance:** [`GOVERNANCE.md`](./GOVERNANCE.md)
+>
 > 🌍 Site/docs: **https://rak.ad/mcp** · 📦 npm: `@rak-ad/mcp` · 🔌 Remote: `https://rak.ad/api/mcp/rak/mcp`
 >
-> 📜 **RAK language spec (v0.1):** [`SPEC.md`](./SPEC.md) — the open standard "write once → own it → cited by every agent".
+> 📜 **RAK language spec (v0.2):** [`SPEC.md`](./SPEC.md) — the open standard "write once → own it → cited by every agent". One envelope for **content and market** ([FOP profile](./docs/profiles/fop.md)).
 >
@@ -110,2 +112,28 @@ > 💸 **Economics (the moat):** [`ECONOMICS.md`](./ECONOMICS.md) — pay-per-AI-citation. Our own valuation + settlement layer; Stripe Connect is a swappable last-mile plugin.
 
+## Who's behind this
+
+RAK OS is an **independent, self-funded** project — no venture capital, no private equity, no big-media owner. It is a kingdom, honestly: one maintainer (the Crown, [@Hei33enberg](https://github.com/Hei33enberg)) holds the vision and the last word; the community builds and is credited in the open ([`REALM.md`](./REALM.md)). Why this structure — and how it's kept hard to capture — is in the [Manifesto](./MANIFESTO.md) and the Realm's absorption-proofing section.
+
+## Build your own RAK
+
+The OS is MIT — **fork your country's RAK, for free, forever.**
+
+- **Build an agent on RAK:** `npx create-rak-agent <name>` — it speaks `rak_*`, shares one base and one citation market. Ship it and it's discoverable via `rak_meta_list_agents`.
+- **Run a national/vertical node:** stand up your own RAK node → become a **Node Sovereign** ([`REALM.md`](./REALM.md), L5). The RAK trademark and origin brand stay with the Crown; everything else is yours.
+- Start from [`SPEC.md`](./SPEC.md) (the contract) and the [skills](./skills).
+
+## One language — content + market
+
+RAK's content object shares a **base envelope** ([`SPEC.md §3.1`](./SPEC.md)) with a sibling protocol, **POXI / FOP** (opinions → listings → gigs). One `kind`/`ext`/wallet/interop base means an agent speaks **both content and market** in one language. Mapping: [`docs/profiles/fop.md`](./docs/profiles/fop.md). Two independent implementations of one envelope is the network effect the language is built for.
+
+## Built on Open Mercato
+
+RAK (and POXI) run on **[Open Mercato](https://github.com/open-mercato/open-mercato)** — an open, inspectable runtime engine. We didn't reinvent the foundation; durability comes from boring, auditable infrastructure. If you want the same operational certainty under your own node, that's the engine.
+
+## Community
+
+- **Discussions:** GitHub Discussions (once enabled) — questions, RFCs, show-and-tell.
+- **Contribute:** [`CONTRIBUTING.md`](./CONTRIBUTING.md) — humans and AI agents both ([`AGENTS.md`](./AGENTS.md)).
+- **Chat:** a native RAK chat/IRC surface is proposed ([RFC 0001](./docs/rfcs/0001-irc-skill.md)) — the goal is that community chat eventually runs on RAK itself.
+
 ## Companion / Powiązane — Strajk Polski
@@ -112,0 +140,0 @@ RAK = bieżące, lokalne newsy i wiedza o Polsce. **Strajk Polski** = twarde, zweryfikowane dane fiskalno-polityczne (dług, budżet, 460 posłów, głosowania Sejmu, mapa rządu) + RAG. Razem: **cała Polska dla agentów AI w jednym miejscu.**

skills/research.md

@@ -13,5 +13,5 @@ # SKILL: rak-research — research & retrieval
 | `rak_research_extract` | any URL → clean markdown (SSRF-safe) | paid |
-| `rak_rag_find_related` | related articles (similarity) | paid |
-| `rak_rag_semantic_search` | dense search over embeddings | paid |
 
+> Retrieval over the RAK archive (`rak_rag_find_related`, `rak_rag_semantic_search`) is a **free reader** capability — see [`rag.md`](./rag.md).
+
 ## Tier / cost
@@ -18,0 +18,0 @@ `rak_research_web` is free with a hard 5/day/IP limit. The rest are `paid` (credits per RAK pricing).

No alert changes

Improved metrics

Total package byte prevSize

26464

82.1%

Number of package files

15

50%

Lines of code

48

77.78%

Number of lines in readme file

150

22.95%

No dependency changes