ask-refined-element-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,162 @@
+/**
+ * MCP server wiring for Ask Refined Element.
+ *
+ * Registers six tools over a shared {@link AskReClient}. Tool descriptions
+ * are written for agent consumption (what you get, when to use it) and mirror
+ * the product's Agent Endpoints spec. The heavy lifting lives in tools.ts.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { AskReClient } from "./api.js";
+import { getArticle, getChecklist, getPaidPlaybook, listArticles, requestConsultation, searchKnowledge, } from "./tools.js";
+export const SERVER_NAME = "ask-refined-element";
+export const SERVER_VERSION = "0.1.0";
+/**
+ * Known taxonomy values, listed in the tool descriptions as EXAMPLES only.
+ * The knowledge pack is CMS-managed (Xperience by Kentico) and the filter is a
+ * plain client-side string match, so these are deliberately NOT baked into the
+ * schema as enums — new CMS values must keep working in already-installed
+ * copies of this package.
+ */
+const KNOWN_TOPICS = ["kentico-upgrades", "geo", "ai-development", "sentinel", "cms-architecture"];
+const KNOWN_AUDIENCES = ["developer", "marketer", "decision-maker", "agent"];
+const SEARCH_DESCRIPTION = "Full-text search over the Ask Refined Element knowledge pack — blog articles, FAQs, case " +
+    "studies, services, checklists, and premium playbooks covering Xperience by Kentico upgrades, " +
+    "GEO (generative engine optimization), AI-driven development, Sentinel for Xperience by Kentico, " +
+    "and CMS architecture. Returns ranked matches, each with an answer-first summary you can cite " +
+    "directly or use to decide which item to fetch in full. Blog articles, FAQs, case studies, and " +
+    "services are read in full with get_article. Free checklists are fetched in full with " +
+    "get_checklist. Premium items return a summary and slug only — retrieve their full body with " +
+    "get_paid_playbook. Use this as the entry point whenever you need Refined Element's expertise on " +
+    "Kentico, GEO, or agent-ready CMS.";
+const LIST_ARTICLES_DESCRIPTION = "List the most recent posts from the Refined Element blog — each with its title, publish date, " +
+    "a one-line summary, and the slug to read it in full. Use this to see what Refined Element has " +
+    "published on Xperience by Kentico, GEO, AI-driven development, and agent commerce, then call " +
+    "get_article(slug) for the complete text. Returns newest-first, up to 50 (default 10).";
+const GET_ARTICLE_DESCRIPTION = "Read one full Refined Element blog article by slug (get slugs from list_articles or " +
+    "search_refined_element_knowledge). Returns the title, publish date, summary, and the complete " +
+    "article body converted from HTML to readable text — headings, lists, and links preserved — plus " +
+    "the canonical URL. Unknown slugs return a not-found result.";
+const REQUEST_CONSULTATION_DESCRIPTION = "Send a consultation request straight to Mike Rahel at Refined Element — for Xperience by Kentico " +
+    "upgrades, AI-driven development, or agent-first (GEO) work. Submit your name, email, and message; " +
+    "Mike reads every one personally, so include enough context (what you're building, your Kentico " +
+    "version, timeline) 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.";
+const CHECKLIST_DESCRIPTION = "Fetch one full free checklist from the Ask Refined Element pack by slug " +
+    "(e.g. geo-readiness-checklist-basic). Returns the checklist's title, summary, topic, " +
+    "audience, and complete ordered steps — each with its one-line action and an explanatory " +
+    "sentence — ready to follow, quote, or hand to a user. If the slug names a premium checklist " +
+    "the response explains it is paid and points you to get_paid_playbook. Unknown slugs return a " +
+    "not-found result. Get valid slugs from search_refined_element_knowledge.";
+const PLAYBOOK_DESCRIPTION = "Retrieve one premium item from the Ask Refined Element pack by slug. Premium items are " +
+    "L402-gated (typically 100 sats); discover them and their slugs with " +
+    "search_refined_element_knowledge — they are marked [PREMIUM]. Call this tool FIRST with only " +
+    "the slug: the endpoint answers HTTP 402 Payment Required with a Lightning invoice and a " +
+    "macaroon, which this tool returns as structured payment instructions. Pay the invoice (the " +
+    "free Lightning Enable MCP server can do this automatically " +
+    "— github.com/refined-element/lightning-enable-mcp), then call this tool AGAIN with the same " +
+    "slug plus the macaroon and the payment preimage to receive the full content.";
+export function createServer(clientOptions = {}) {
+    const client = new AskReClient(clientOptions);
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    server.registerTool("search_refined_element_knowledge", {
+        title: "Search Refined Element knowledge",
+        description: SEARCH_DESCRIPTION,
+        inputSchema: {
+            query: z.string().min(1).describe("Search terms (required)."),
+            topic: z
+                .string()
+                .optional()
+                .describe("Optional topic filter applied to the returned matches (exact string match). " +
+                `Known topics include: ${KNOWN_TOPICS.join(", ")}. ` +
+                "The pack is CMS-managed, so new topics may appear — any string is accepted."),
+            audience: z
+                .string()
+                .optional()
+                .describe("Optional audience filter applied to the returned matches (exact string match). " +
+                `Known audiences include: ${KNOWN_AUDIENCES.join(", ")}. ` +
+                "The pack is CMS-managed, so new audiences may appear — any string is accepted."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe("Maximum number of matches to return (default 5, max 20)."),
+        },
+    }, async (args) => searchKnowledge(client, args));
+    server.registerTool("get_checklist", {
+        title: "Get a free checklist",
+        description: CHECKLIST_DESCRIPTION,
+        inputSchema: {
+            slug: z
+                .string()
+                .min(1)
+                .describe("Checklist slug, e.g. geo-readiness-checklist-basic."),
+        },
+    }, async ({ slug }) => getChecklist(client, slug));
+    server.registerTool("get_paid_playbook", {
+        title: "Get a premium (L402-paid) playbook",
+        description: PLAYBOOK_DESCRIPTION,
+        inputSchema: {
+            slug: z
+                .string()
+                .min(1)
+                .describe("Premium item slug, as discovered via search_refined_element_knowledge " +
+                "(premium matches are marked [PREMIUM] and include their slug)."),
+            macaroon: z
+                .string()
+                .optional()
+                .describe("The macaroon from the 402 challenge. Omit on the first call."),
+            preimage: z
+                .string()
+                .optional()
+                .describe("The Lightning payment preimage proving you settled the invoice. Omit on the first call."),
+        },
+    }, async (args) => getPaidPlaybook(client, args));
+    server.registerTool("list_articles", {
+        title: "List recent blog articles",
+        description: LIST_ARTICLES_DESCRIPTION,
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Maximum number of articles to return (default 10, max 50, newest first)."),
+        },
+    }, async (args) => listArticles(client, args));
+    server.registerTool("get_article", {
+        title: "Read a full blog article",
+        description: GET_ARTICLE_DESCRIPTION,
+        inputSchema: {
+            slug: z
+                .string()
+                .min(1)
+                .describe("Article slug, as discovered via list_articles or search_refined_element_knowledge."),
+        },
+    }, async ({ slug }) => getArticle(client, slug));
+    server.registerTool("request_consultation", {
+        title: "Request a consultation from Refined Element",
+        description: REQUEST_CONSULTATION_DESCRIPTION,
+        inputSchema: {
+            name: z.string().min(1).describe("Your name (required)."),
+            email: z
+                .string()
+                .min(1)
+                .describe("Reply-to email address (required). Shape-checked locally; validated by the API."),
+            message: z
+                .string()
+                .min(1)
+                .describe("What you need help with (required). Include enough context for Mike to act on."),
+            company: z.string().optional().describe("Your company or project name (optional)."),
+            priority: z
+                .boolean()
+                .optional()
+                .describe("Set true to flag the request as urgent (free — no payment). Omit or false for a normal request."),
+        },
+    }, async (args) => requestConsultation(client, args));
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Tool logic for the Ask Refined Element MCP server.
+ *
+ * Each exported function takes an {@link AskReClient} plus validated input and
+ * resolves to an MCP tool result ({ content, isError }). The logic is kept out
+ * of the transport wiring in server.ts so it can be unit-tested by driving a
+ * client backed by a mock fetch.
+ */
+import type { AskReClient } from "./api.js";
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    /** Present so the shape stays assignable to the MCP SDK's CallToolResult. */
+    [key: string]: unknown;
+}
+export interface SearchInput {
+    query: string;
+    topic?: string;
+    audience?: string;
+    limit?: number;
+}
+export declare function searchKnowledge(client: AskReClient, input: SearchInput): Promise<ToolResult>;
+export declare function getChecklist(client: AskReClient, slug: string): Promise<ToolResult>;
+export interface PlaybookInput {
+    slug: string;
+    macaroon?: string;
+    preimage?: string;
+}
+export declare function getPaidPlaybook(client: AskReClient, input: PlaybookInput): Promise<ToolResult>;
+export interface ListArticlesInput {
+    limit?: number;
+}
+export declare function listArticles(client: AskReClient, input: ListArticlesInput): Promise<ToolResult>;
+export declare function getArticle(client: AskReClient, slug: string): Promise<ToolResult>;
+export interface ConsultationInput {
+    name: string;
+    email: string;
+    message: string;
+    company?: string;
+    priority?: boolean;
+}
+export declare function requestConsultation(client: AskReClient, input: ConsultationInput): Promise<ToolResult>;
+/**
+ * Converts an HTML article body to readable plain text / lightweight Markdown:
+ * headings become `#`-prefixed lines, list items become `-` bullets, links
+ * become `text (href)`, and paragraph/`<br>` boundaries become blank lines.
+ * Everything else is stripped and common HTML entities are decoded. Anchors are
+ * resolved BEFORE headings/list items so links survive inside them.
+ */
+export declare function htmlToText(html: string): string;