<!-- mcp-name: io.github.refined-element/ask-refined-element -->

Part of [Refined Element](https://refinedelement.com) — an independent consultancy for Xperience by Kentico upgrades, AI-driven development, and agent-first marketing (GEO).

# Ask Refined Element MCP Server

An open-source MCP (Model Context Protocol) server that lets AI agents query Refined Element's knowledge pack: field-tested guidance on Xperience by Kentico upgrades, GEO (generative engine optimization), AI-driven development, Sentinel for Xperience by Kentico, and agent-ready CMS architecture.

The knowledge pack is **authored once in Xperience by Kentico and served headless** — to humans on the website, to AI crawlers via `llms.txt`, and to agents through this MCP server. This server is one of those delivery surfaces, and a working example of the agent-ready CMS pattern the pack itself describes.

Most of the pack is free — including priority consultation requests. Two knowledge items are premium, gated behind a single **L402 (Lightning) payment of 100 sats** — a demonstration of metered, pay-per-access content on the same content model.

## What It Does

Give your AI agent this server and it can:

- **Search the knowledge pack** — ranked, answer-first summaries it can cite directly, across blog articles, FAQs, case studies, services, checklists, and premium playbooks on Kentico upgrades, GEO, AI development, Sentinel, and CMS architecture. FAQ, case study, and service matches come back with their content inline, so the match itself is the answer.
- **Browse the whole pack** — call the same search tool with no query to get an index of every item, grouped by content type, before deciding what to read.
- **Fetch a full checklist** — complete, ordered, actionable steps by slug (e.g. the GEO readiness checklist).
- **Read the blog** — list recent Refined Element articles and read any one in full, with its HTML converted to clean text (headings, lists, and links preserved).
- **Request a consultation** — send a message straight to Mike Rahel; set `priority: true` to flag it as urgent (free — no payment).
- **Buy a premium playbook** — retrieve an L402-gated item: the tool returns the Lightning invoice on the first call, then the full content once the agent has paid.

## Tools

| Tool | Paid | What you get |
|------|------|--------------|
| `search_refined_element_knowledge` | Free | Ranked matches with answer-first summaries across articles, FAQs, case studies, services, checklists, and playbooks. Blog article hits point at `get_article`; FAQ, case study, and service hits carry their answer inline; premium hits are flagged with their price and the slug to buy them. With no query, returns an index of the whole pack. |
| `get_checklist` | Free | One full free checklist by slug — title, summary, topic, audience, and every ordered step. |
| `list_articles` | Free | Recent blog articles, newest first — title, publish date, one-line summary, url, and the slug to read each in full. |
| `get_article` | Free | One full blog article by slug — HTML converted to readable text (headings, lists, and links preserved), plus its canonical URL. |
| `request_consultation` | Free | Send a consultation request to Mike Rahel. Set `priority: true` to flag it as urgent — still free, no payment. |
| `get_paid_playbook` | 100 sats (L402) | One premium item by slug. First call returns a Lightning invoice + macaroon; a second call with the paid credential returns the full content. |

### `search_refined_element_knowledge`

Full-text search over the pack. Returns ranked matches, each with an answer-first summary you can cite directly or use to decide which item to fetch in full. Premium items return a summary and slug only — get their body with `get_paid_playbook`. Free checklists can be pulled in full with `get_checklist`.

```json
{
  "query": "kentico upgrade risk",   // optional — omit it to browse the index
  "topic": "kentico-upgrades",       // optional filter
  "audience": "decision-maker",       // optional filter
  "limit": 5                          // optional, default 5, max 20
}
```

**What a match looks like.** Blog articles and checklists carry a `slug`, and the match tells you which tool reads it in full (`get_article`, `get_checklist`, or `get_paid_playbook` for `[PREMIUM]` items). FAQs, case studies, and services have no slug and no separate page to fetch — their body, a case study's headline metrics, and a "→ More" link are rendered inline, so no follow-up call is needed.

**Browsing the index.** Call the tool with no `query` (or an empty one) and it returns an index of the whole pack instead of searching — every item grouped by content type (knowledge articles, checklists, Sentinel rules, agent endpoints), each with its title, slug, `[PREMIUM]` badge where it applies, and a one-line summary. It is the cheapest way for an agent to see what exists before it guesses at search terms.

`topic` and `audience` accept any string and are matched exactly against each result — the taxonomy is owned by the CMS, so new values keep working without a package upgrade. Known `topic` values today (examples): `kentico-upgrades`, `geo`, `ai-development`, `sentinel`, `cms-architecture`. Known `audience` values today (examples): `developer`, `marketer`, `decision-maker`, `agent`. Every field is optional.

### `get_checklist`

Fetch one full free checklist by slug, e.g. `geo-readiness-checklist-basic`. Returns the complete ordered step list — each step with its one-line action and an explanatory sentence — ready to follow, quote, or hand to a user. If the slug is a premium checklist, the response points you to `get_paid_playbook`. Unknown slugs return a not-found result.

```json
{ "slug": "geo-readiness-checklist-basic" }
```

### `list_articles`

List the most recent posts from the Refined Element blog, newest first. Each entry has its title, publish date, a one-line summary, the canonical URL, and the slug to read it in full with `get_article`.

```json
{ "limit": 10 }   // optional, default 10, max 50
```

### `get_article`

Read one full blog article by slug (discover slugs with `list_articles` or `search_refined_element_knowledge`). Returns the title, publish date, summary, the complete body converted from HTML to readable text — headings, lists, and links preserved — and the canonical URL. Unknown slugs return a not-found result.

```json
{ "slug": "agent-ready-cms-xperience" }
```

### `request_consultation`

Send a consultation request straight to Mike Rahel — for Xperience by Kentico upgrades, AI-driven development, or agent-first (GEO) work. The email is shape-checked locally (a quick `@`/length sanity check) and fully validated by the API.

```json
{
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "message": "We need help upgrading a KX13 site to Xperience by Kentico.",
  "company": "Analytical Engines Ltd",  // optional
  "priority": false                      // optional; true = flag as urgent (free)
}
```

Mike reads every request personally, so include enough context for him to act on it. Set `priority: true` to flag the request as urgent so Mike sees the urgency — priority is free, no payment required.

### `get_paid_playbook` (L402-gated)

Retrieve one premium item by slug, gated at 100 sats via L402. Discover the current premium items and their slugs with `search_refined_element_knowledge` — they are flagged `[PREMIUM]`. (Examples at the time of writing: `agent-ready-cms-checklist-full`, `kentico-upgrade-risk-triage` — the CMS owns the catalog, so this list can grow without a package release.)

```json
{
  "slug": "kentico-upgrade-risk-triage",
  "macaroon": "…",   // omit on the first call
  "preimage": "…"     // omit on the first call
}
```

See [The L402 payment flow](#the-l402-payment-flow) below.

## Requirements

- **Node.js ≥ 22.**
- **The Ask Refined Element API (`/api/ask/*`) must be live at the configured base URL.** The default is the production site, `https://refinedelement.com`. If the API is not reachable there — for example while it is still being deployed, or when you run the site locally — point the server at the right host with the `ASK_RE_BASE_URL` environment variable (see [Development](#development)). When the base URL answers with an HTML page instead of API JSON, the tools report that the API is not deployed/reachable there rather than pretending content does not exist.

## Quick Install

Run it with no install:

```bash
npx -y ask-refined-element-mcp
```

## Claude Code

```bash
claude mcp add ask-refined-element -- npx -y ask-refined-element-mcp
```

Or add it to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "ask-refined-element": {
      "command": "npx",
      "args": ["-y", "ask-refined-element-mcp"]
    }
  }
}
```

## Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ask-refined-element": {
      "command": "npx",
      "args": ["-y", "ask-refined-element-mcp"]
    }
  }
}
```

Config file locations:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/claude/claude_desktop_config.json`

No API key, wallet, or secret is needed to install or run this server — it calls only public endpoints. A Lightning wallet is needed only to unlock the two premium items (see below).

## The L402 Payment Flow

Two knowledge items are premium and gated with **L402** — the HTTP 402 "Payment Required" standard for pay-per-access over Lightning. `get_paid_playbook` handles both halves of the exchange:

1. **Ask for the item.** Call `get_paid_playbook` with only the `slug`. The endpoint answers `402 Payment Required` with a Lightning **invoice** (100 sats) and a **macaroon**. The tool returns these as structured payment instructions — it does not error.
2. **Pay the invoice.** Pay the Lightning invoice with any wallet that returns a payment **preimage**. The easiest path for an agent is the free [**Lightning Enable MCP server**](https://github.com/refined-element/lightning-enable-mcp) and its `pay_invoice` tool — connect a wallet via NWC or Strike ([docs.lightningenable.com](https://docs.lightningenable.com)) and it pays, tracks, and budgets automatically.
3. **Unlock the content.** Call `get_paid_playbook` again with the **same slug** plus the `macaroon` from step 1 and the `preimage` from step 2. The tool sends `Authorization: L402 <macaroon>:<preimage>` and returns the full item.

If a credential fails to verify, the tool returns a fresh challenge with the same guidance, so the agent can retry cleanly. Run both the Lightning Enable MCP and this server together and an agent can discover, pay for, and read a premium playbook end to end without a human in the loop.

## Development

Clone, install, build, and run the smoke tests:

```bash
git clone https://github.com/refined-element/ask-refined-element.git
cd ask-refined-element
npm install
npm run build      # tsc → dist/
npm test           # vitest — mocks fetch, asserts each tool + the 402 flow
```

Run against a local Ask Refined Element API instead of production with the `ASK_RE_BASE_URL` environment variable:

```bash
# Default is https://refinedelement.com
ASK_RE_BASE_URL=http://localhost:23918 npx -y ask-refined-element-mcp

# The local re-xbk app may serve the API on :23918 or :23917
ASK_RE_BASE_URL=http://localhost:23917 node dist/index.js
```

In a client config, set it under `env`:

```json
{
  "mcpServers": {
    "ask-refined-element": {
      "command": "node",
      "args": ["/absolute/path/to/ask-refined-element/dist/index.js"],
      "env": { "ASK_RE_BASE_URL": "http://localhost:23918" }
    }
  }
}
```

`npm run dev` runs the TypeScript entry point directly via `tsx` without a build step.

### Project structure

```
ask-refined-element/
├── src/
│   ├── index.ts    # stdio entry point (bin)
│   ├── server.ts   # MCP server + tool registration (zod schemas)
│   ├── tools.ts    # tool logic + response formatting
│   ├── api.ts      # public HTTP client (10s timeout, clean error shaping)
│   └── types.ts    # API response shapes
├── test/
│   └── tools.test.ts
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── LICENSE
```

## Related Projects

- [Lightning Enable MCP](https://github.com/refined-element/lightning-enable-mcp) — give your agent a Lightning wallet; pays L402 challenges (including this server's premium items) automatically.
- [Lightning Enable](https://lightningenable.com) — infrastructure for agent commerce over Lightning.
- [Lightning Enable Docs](https://docs.lightningenable.com) — wallet setup (NWC, Strike) and the full L402 guide.

## Links

- [Refined Element](https://refinedelement.com) — the consultancy, and the live knowledge pack.
- [Sentinel for Xperience by Kentico](https://github.com/refined-element/xperience-community-sentinel) — the free, open-source Kentico health scanner referenced throughout the pack.

## License

MIT © Refined Element, LLC — see [LICENSE](LICENSE).