isagentready-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bart Waardenburg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# isagentready-mcp
+
+[![npm version](https://img.shields.io/npm/v/isagentready-mcp.svg)](https://www.npmjs.com/package/isagentready-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+[![CI](https://github.com/bartwaardenburg/isagentready-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bartwaardenburg/isagentready-mcp/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/BartWaardenburg/dc467336d6825cc861b82bee7a38397c/raw/isagentready-mcp-coverage.json)](https://bartwaardenburg.github.io/isagentready-mcp/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [IsAgentReady](https://isagentready.com) API. Scan any website for AI agent readiness and get detailed reports with scores, letter grades, and actionable recommendations across 5 categories: Discovery, Structured Data, Semantics, Agent Protocols, and Security.
+
+## Features
+
+- **3 MCP tools** for scanning, retrieving results, and browsing rankings
+- **No API key required** — public API, zero configuration needed
+- **Built-in caching** with configurable TTL and automatic invalidation on scans
+- **Retry logic** with exponential backoff and `Retry-After` header support
+- **Structured content** returned alongside human-readable text
+- **Toolset filtering** to expose only the tool categories you need
+- **Actionable error messages** with context-aware recovery suggestions
+- **Docker support** for containerized deployment
+- **97 unit tests** across 7 test files
+
+## Supported Clients
+
+This MCP server works with any client that supports the Model Context Protocol, including:
+
+| Client | Easiest install |
+|---|---|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | One-liner: `claude mcp add` |
+| [Codex CLI](https://github.com/openai/codex) (OpenAI) | One-liner: `codex mcp add` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) (Google) | One-liner: `gemini mcp add` |
+| [VS Code](https://code.visualstudio.com/) (Copilot) | Command Palette: `MCP: Add Server` |
+| [Claude Desktop](https://claude.ai/download) | JSON config file |
+| [Cursor](https://cursor.com) | JSON config file |
+| [Windsurf](https://codeium.com/windsurf) | JSON config file |
+| [Cline](https://github.com/cline/cline) | UI settings |
+| [Zed](https://zed.dev) | JSON settings file |
+
+## Installation
+
+### Claude Code
+
+```bash
+claude mcp add isagentready-mcp -- npx -y isagentready-mcp
+```
+
+### Codex CLI (OpenAI)
+
+```bash
+codex mcp add isagentready-mcp -- npx -y isagentready-mcp
+```
+
+### Gemini CLI (Google)
+
+```bash
+gemini mcp add isagentready-mcp -- npx -y isagentready-mcp
+```
+
+### VS Code (Copilot)
+
+Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) > `MCP: Add Server` > select **Command (stdio)**.
+
+Or add to `.vscode/mcp.json` in your project directory:
+
+```json
+{
+  "servers": {
+    "isagentready-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "isagentready-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop / Cursor / Windsurf / Cline
+
+These clients share the same JSON format. Add the config below to the appropriate file:
+
+| Client | Config file |
+|---|---|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor (project) | `.cursor/mcp.json` |
+| Cursor (global) | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| Cline | Settings > MCP Servers > Edit |
+
+```json
+{
+  "mcpServers": {
+    "isagentready-mcp": {
+      "command": "npx",
+      "args": ["-y", "isagentready-mcp"]
+    }
+  }
+}
+```
+
+### Zed
+
+Add to your Zed settings (`~/.zed/settings.json` on macOS, `~/.config/zed/settings.json` on Linux):
+
+```json
+{
+  "context_servers": {
+    "isagentready-mcp": {
+      "command": "npx",
+      "args": ["-y", "isagentready-mcp"]
+    }
+  }
+}
+```
+
+### Docker
+
+```bash
+docker run -i --rm ghcr.io/bartwaardenburg/isagentready-mcp
+```
+
+### Codex CLI (TOML config alternative)
+
+If you prefer editing `~/.codex/config.toml` directly:
+
+```toml
+[mcp_servers.isagentready-mcp]
+command = "npx"
+args = ["-y", "isagentready-mcp"]
+```
+
+### Other MCP Clients
+
+For any MCP-compatible client, use this server configuration:
+
+- **Command:** `npx`
+- **Args:** `["-y", "isagentready-mcp"]`
+- **No environment variables required**
+
+## Configuration
+
+All configuration is optional via environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `ISAGENTREADY_CACHE_TTL` | Response cache lifetime in seconds. Set to `0` to disable caching. | `120` |
+| `ISAGENTREADY_MAX_RETRIES` | Maximum retry attempts for rate-limited (429) requests with exponential backoff. | `3` |
+| `ISAGENTREADY_BASE_URL` | API base URL. | `https://isagentready.com` |
+| `ISAGENTREADY_TOOLSETS` | Comma-separated list of tool categories to enable (see [Toolset Filtering](#toolset-filtering)). | All toolsets |
+
+### Example with configuration
+
+```json
+{
+  "mcpServers": {
+    "isagentready-mcp": {
+      "command": "npx",
+      "args": ["-y", "isagentready-mcp"],
+      "env": {
+        "ISAGENTREADY_CACHE_TTL": "300",
+        "ISAGENTREADY_MAX_RETRIES": "5"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Scans
+
+| Tool | Description |
+|---|---|
+| `scan_website` | Trigger a new scan of a website for AI agent readiness. Returns cached results if scanned within the last hour. |
+| `get_scan_results` | Get the latest scan results for a domain with scores, grades, and recommendations. |
+
+### Rankings
+
+| Tool | Description |
+|---|---|
+| `get_rankings` | Browse paginated AI readiness rankings with filtering by grade range, search, and sorting. |
+
+## Toolset Filtering
+
+Reduce context window usage by enabling only the tool categories you need. Set the `ISAGENTREADY_TOOLSETS` environment variable to a comma-separated list:
+
+```bash
+ISAGENTREADY_TOOLSETS=scans
+```
+
+| Toolset | Tools included |
+|---|---|
+| `scans` | `scan_website`, `get_scan_results` |
+| `rankings` | `get_rankings` |
+
+When not set, all toolsets are enabled. Invalid names are ignored; if all names are invalid, all toolsets are enabled as a fallback.
+
+## Example Usage
+
+Once connected, you can interact with the IsAgentReady API using natural language:
+
+- "Scan example.com for AI agent readiness"
+- "Check if the scan results for example.com are ready"
+- "Show me the top AI-ready websites"
+- "Search the rankings for sites in the high grade range"
+- "How does my site compare to others?"
+
+### Scan + fix workflow
+
+Combine with the [isagentready-skills](https://github.com/bartwaardenburg/isagentready-skills) agent skills for a full scan, fix, and re-verify workflow:
+
+```
+> Scan example.com for AI agent readiness
+
+Scan enqueued for example.com
+Status: pending
+
+> Check the results for example.com
+
+Domain: example.com
+Grade: B (72/100)
+Status: completed
+
+Discovery — 15/20 (75%, weight: 30%)
+  [PASS] 1.1 robots.txt (5/5)
+  [FAIL] 1.2 sitemap.xml (0/5)
+    Recommendation: Add a sitemap.xml file...
+
+> Fix the failing checkpoints
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Run tests
+pnpm test
+
+# Type check
+pnpm typecheck
+```
+
+### Project Structure
+
+```
+src/
+  index.ts              # Entry point (stdio transport)
+  server.ts             # MCP server setup, toolset filtering
+  client.ts             # IsAgentReady API HTTP client with caching and retry
+  cache.ts              # TTL-based in-memory response cache
+  types.ts              # TypeScript interfaces
+  format.ts             # Output formatting helpers
+  tool-result.ts        # Error formatting with recovery suggestions
+  update-checker.ts     # NPM update notifications
+  tools/
+    scans.ts            # scan_website, get_scan_results
+    rankings.ts         # get_rankings
+```
+
+## Requirements
+
+- Node.js >= 20
+
+## Related
+
+- [isagentready-skills](https://github.com/bartwaardenburg/isagentready-skills) — Agent skills for fixing AI readiness issues identified by scans
+- [IsAgentReady.com](https://isagentready.com) — The web scanner
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/cache.d.ts

@@ -0,0 +1,10 @@
+export declare class TtlCache {
+    private readonly store;
+    private readonly defaultTtlMs;
+    constructor(defaultTtlMs?: number);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttlMs?: number): void;
+    invalidate(pattern: string): void;
+    clear(): void;
+    get size(): number;
+}

package/dist/cache.js

@@ -0,0 +1,36 @@
+export class TtlCache {
+    store = new Map();
+    defaultTtlMs;
+    constructor(defaultTtlMs = 120_000) {
+        this.defaultTtlMs = defaultTtlMs;
+    }
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, ttlMs) {
+        this.store.set(key, {
+            value,
+            expiresAt: Date.now() + (ttlMs ?? this.defaultTtlMs),
+        });
+    }
+    invalidate(pattern) {
+        for (const key of this.store.keys()) {
+            if (key.includes(pattern)) {
+                this.store.delete(key);
+            }
+        }
+    }
+    clear() {
+        this.store.clear();
+    }
+    get size() {
+        return this.store.size;
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import type { ScanResult, ScanPending, ScanEnqueued, RankingsResponse } from "./types.js";
+export declare class IsAgentReadyApiError extends Error {
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status: number, details?: unknown | undefined);
+}
+interface ClientOptions {
+    maxRetries?: number;
+    cacheTtlMs?: number;
+}
+export declare class IsAgentReadyClient {
+    private readonly baseUrl;
+    private readonly cache;
+    private readonly maxRetries;
+    constructor(baseUrl?: string, options?: ClientOptions);
+    private request;
+    getScanResults(domain: string): Promise<ScanResult | ScanPending>;
+    createScan(url: string): Promise<ScanEnqueued | ScanResult>;
+    getRankings(params?: {
+        page?: number;
+        per_page?: number;
+        grade_range?: "high" | "mid" | "low";
+        search?: string;
+        sort?: "score_desc" | "score_asc" | "domain" | "newest";
+    }): Promise<RankingsResponse>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,79 @@
+import { TtlCache } from "./cache.js";
+export class IsAgentReadyApiError extends Error {
+    status;
+    details;
+    constructor(message, status, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+    }
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class IsAgentReadyClient {
+    baseUrl;
+    cache;
+    maxRetries;
+    constructor(baseUrl = "https://isagentready.com", options = {}) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.cache = new TtlCache(options.cacheTtlMs ?? 120_000);
+        this.maxRetries = options.maxRetries ?? 3;
+    }
+    async request(method, path, body, cacheKey) {
+        if (cacheKey) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== undefined)
+                return cached;
+        }
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const url = `${this.baseUrl}${path}`;
+            const headers = new Headers({ "Content-Type": "application/json" });
+            const init = { method, headers };
+            if (body) {
+                init.body = JSON.stringify(body);
+            }
+            const response = await fetch(url, init);
+            if (response.status === 429 && attempt < this.maxRetries) {
+                const retryAfter = response.headers.get("retry-after");
+                const delayMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000;
+                await sleep(delayMs);
+                continue;
+            }
+            if (!response.ok) {
+                const errorBody = await response.json().catch(() => null);
+                throw new IsAgentReadyApiError(errorBody?.error ?? `HTTP ${response.status}`, response.status, errorBody);
+            }
+            const data = (await response.json());
+            if (cacheKey) {
+                this.cache.set(cacheKey, data);
+            }
+            return data;
+        }
+        throw new Error("Request failed after retries");
+    }
+    async getScanResults(domain) {
+        const encoded = encodeURIComponent(domain);
+        return this.request("GET", `/api/v1/scan/${encoded}`, undefined, `scan:${domain}`);
+    }
+    async createScan(url) {
+        this.cache.invalidate("scan:");
+        this.cache.invalidate("rankings:");
+        return this.request("POST", "/api/v1/scan", { url });
+    }
+    async getRankings(params = {}) {
+        const searchParams = new URLSearchParams();
+        if (params.page !== undefined)
+            searchParams.set("page", String(params.page));
+        if (params.per_page !== undefined)
+            searchParams.set("per_page", String(params.per_page));
+        if (params.grade_range)
+            searchParams.set("grade_range", params.grade_range);
+        if (params.search)
+            searchParams.set("search", params.search);
+        if (params.sort)
+            searchParams.set("sort", params.sort);
+        const query = searchParams.toString();
+        const path = `/api/v1/rankings${query ? `?${query}` : ""}`;
+        const cacheKey = `rankings:${query}`;
+        return this.request("GET", path, undefined, cacheKey);
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,5 @@
+import type { ScanResult, Category, Checkpoint } from "./types.js";
+export declare const formatCheckpoint: (cp: Checkpoint) => string;
+export declare const formatCategory: (cat: Category) => string;
+export declare const formatScanResult: (scan: ScanResult) => string;
+export declare const formatScanSummary: (scan: ScanResult) => string;

package/dist/format.js

@@ -0,0 +1,37 @@
+const statusIcon = {
+    pass: "[PASS]",
+    partial: "[PARTIAL]",
+    fail: "[FAIL]",
+    skip: "[SKIP]",
+};
+export const formatCheckpoint = (cp) => {
+    const lines = [
+        `  ${statusIcon[cp.status] ?? cp.status} ${cp.id} ${cp.name} (${cp.score}/${cp.max_score})`,
+    ];
+    if (cp.details)
+        lines.push(`    Details: ${cp.details}`);
+    if (cp.status !== "pass" && cp.recommendation)
+        lines.push(`    Recommendation: ${cp.recommendation}`);
+    return lines.join("\n");
+};
+export const formatCategory = (cat) => {
+    const pct = cat.max_score > 0 ? Math.round((cat.score / cat.max_score) * 100) : 0;
+    const lines = [
+        `${cat.label} — ${cat.score}/${cat.max_score} (${pct}%, weight: ${cat.weight}%)`,
+        ...cat.checkpoints.map(formatCheckpoint),
+    ];
+    return lines.join("\n");
+};
+export const formatScanResult = (scan) => {
+    const lines = [
+        `Domain: ${scan.domain}`,
+        `Grade: ${scan.letter_grade} (${scan.overall_score}/100)`,
+        `Status: ${scan.status}`,
+        scan.scan_duration_ms ? `Scan duration: ${scan.scan_duration_ms}ms` : "",
+        scan.completed_at ? `Completed: ${scan.completed_at}` : "",
+        "",
+        ...(scan.categories ?? []).map(formatCategory),
+    ];
+    return lines.filter(Boolean).join("\n");
+};
+export const formatScanSummary = (scan) => `${scan.domain} — Grade: ${scan.letter_grade} (${scan.overall_score}/100)`;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { IsAgentReadyClient } from "./client.js";
+import { createServer, parseToolsets } from "./server.js";
+import { checkForUpdate } from "./update-checker.js";
+const require = createRequire(import.meta.url);
+const { name, version } = require("../package.json");
+const cacheTtl = process.env.ISAGENTREADY_CACHE_TTL !== undefined
+    ? parseInt(process.env.ISAGENTREADY_CACHE_TTL, 10) * 1000
+    : undefined;
+const maxRetries = process.env.ISAGENTREADY_MAX_RETRIES !== undefined
+    ? parseInt(process.env.ISAGENTREADY_MAX_RETRIES, 10)
+    : 3;
+const baseUrl = process.env.ISAGENTREADY_BASE_URL ?? "https://isagentready.com";
+const client = new IsAgentReadyClient(baseUrl, { maxRetries, cacheTtlMs: cacheTtl });
+const toolsets = parseToolsets(process.env.ISAGENTREADY_TOOLSETS);
+const server = createServer(client, toolsets);
+const main = async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Fire-and-forget — don't block server startup
+    void checkForUpdate(name, version);
+};
+main().catch((error) => {
+    console.error("IsAgentReady MCP server failed:", error);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IsAgentReadyClient } from "./client.js";
+export type Toolset = "scans" | "rankings";
+export declare const parseToolsets: (env?: string) => Set<Toolset>;
+export declare const createServer: (client: IsAgentReadyClient, toolsets?: Set<Toolset>) => McpServer;

package/dist/server.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerScanTools } from "./tools/scans.js";
+import { registerRankingTools } from "./tools/rankings.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+const ALL_TOOLSETS = ["scans", "rankings"];
+export const parseToolsets = (env) => {
+    if (!env)
+        return new Set(ALL_TOOLSETS);
+    const requested = env.split(",").map((s) => s.trim().toLowerCase());
+    const valid = new Set();
+    for (const name of requested) {
+        if (ALL_TOOLSETS.includes(name)) {
+            valid.add(name);
+        }
+    }
+    return valid.size > 0 ? valid : new Set(ALL_TOOLSETS);
+};
+const toolsetRegistry = {
+    scans: [registerScanTools],
+    rankings: [registerRankingTools],
+};
+export const createServer = (client, toolsets) => {
+    const server = new McpServer({
+        name: "isagentready-mcp",
+        version,
+    });
+    const enabled = toolsets ?? new Set(ALL_TOOLSETS);
+    const registered = new Set();
+    for (const toolset of enabled) {
+        const registerers = toolsetRegistry[toolset];
+        for (const register of registerers) {
+            if (!registered.has(register)) {
+                registered.add(register);
+                register(server, client);
+            }
+        }
+    }
+    return server;
+};

package/dist/tool-result.d.ts

@@ -0,0 +1,14 @@
+export declare const toTextResult: (text: string, structuredContent?: Record<string, unknown>) => {
+    structuredContent?: Record<string, unknown> | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare const toErrorResult: (error: unknown) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/tool-result.js

@@ -0,0 +1,61 @@
+import { IsAgentReadyApiError } from "./client.js";
+export const toTextResult = (text, structuredContent) => ({
+    content: [{ type: "text", text }],
+    ...(structuredContent ? { structuredContent } : {}),
+});
+const getRecoverySuggestion = (status, message, details) => {
+    if (status === 429) {
+        return "Rate limit exceeded. Wait a moment and retry. If scanning, note that recently scanned domains have a 1-hour cooldown.";
+    }
+    if (status === 404) {
+        return "No scan found for this domain. Use scan_website to trigger a new scan first.";
+    }
+    if (status === 400) {
+        const detailStr = typeof details === "string" ? details : JSON.stringify(details ?? "");
+        const lower = detailStr.toLowerCase();
+        if (lower.includes("url")) {
+            return "Invalid or missing URL. Ensure the URL starts with http:// or https://.";
+        }
+        return "Missing required parameter. Ensure the URL or domain is provided.";
+    }
+    if (status === 409) {
+        return "Conflict — a scan for this domain is already in progress. Wait for it to complete, then use get_scan_results to retrieve the results.";
+    }
+    if (status === 422) {
+        return "Invalid URL. The URL must start with http:// or https:// and be a valid website address.";
+    }
+    if (status >= 500) {
+        return "IsAgentReady API server error. This is a temporary issue. Wait a moment and retry.";
+    }
+    return null;
+};
+export const toErrorResult = (error) => {
+    if (error instanceof IsAgentReadyApiError) {
+        const suggestion = getRecoverySuggestion(error.status, error.message, error.details);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `IsAgentReady API error: ${error.message}`,
+                        `Status: ${error.status}`,
+                        error.details ? `Details: ${JSON.stringify(error.details, null, 2)}` : "",
+                        suggestion ? `\nRecovery: ${suggestion}` : "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: error instanceof Error ? error.message : String(error),
+            },
+        ],
+        isError: true,
+    };
+};

package/dist/tools/rankings.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IsAgentReadyClient } from "../client.js";
+export declare const registerRankingTools: (server: McpServer, client: IsAgentReadyClient) => void;

package/dist/tools/rankings.js

@@ -0,0 +1,52 @@
+import * as z from "zod/v4";
+import { formatScanSummary } from "../format.js";
+import { toTextResult, toErrorResult } from "../tool-result.js";
+export const registerRankingTools = (server, client) => {
+    server.registerTool("get_rankings", {
+        title: "Get AI Readiness Rankings",
+        description: "Get a paginated, sorted list of website AI readiness scores. Supports filtering by grade range (high/mid/low), search by domain name, and sorting by score, domain, or newest.",
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+        inputSchema: z.object({
+            page: z.number().int().min(1).default(1).describe("Page number (default: 1)"),
+            per_page: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(25)
+                .describe("Results per page (1-100, default: 25)"),
+            grade_range: z
+                .enum(["high", "mid", "low"])
+                .optional()
+                .describe("Filter by grade range: high (A/A+), mid (B/C), low (D/F)"),
+            search: z.string().optional().describe("Search by domain name"),
+            sort: z
+                .enum(["score_desc", "score_asc", "domain", "newest"])
+                .default("score_desc")
+                .describe("Sort order (default: score_desc)"),
+        }),
+    }, async ({ page, per_page, grade_range, search, sort }) => {
+        try {
+            const result = await client.getRankings({ page, per_page, grade_range, search, sort });
+            const lines = [
+                `AI Readiness Rankings — Page ${result.page}/${result.total_pages} (${result.total} total)`,
+                "",
+                ...result.entries.map((entry, i) => `${(result.page - 1) * result.per_page + i + 1}. ${formatScanSummary(entry)}`),
+            ];
+            if (result.entries.length === 0) {
+                lines.push("No results found.");
+            }
+            return toTextResult(lines.join("\n"), {
+                type: "rankings",
+                page: result.page,
+                per_page: result.per_page,
+                total: result.total,
+                total_pages: result.total_pages,
+                entries: result.entries,
+            });
+        }
+        catch (error) {
+            return toErrorResult(error);
+        }
+    });
+};

package/dist/tools/scans.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { IsAgentReadyClient } from "../client.js";
+export declare const registerScanTools: (server: McpServer, client: IsAgentReadyClient) => void;

package/dist/tools/scans.js

@@ -0,0 +1,67 @@
+import * as z from "zod/v4";
+import { formatScanResult } from "../format.js";
+import { toTextResult, toErrorResult } from "../tool-result.js";
+const isScanCompleted = (result) => result.status === "completed" || result.status === "failed";
+export const registerScanTools = (server, client) => {
+    server.registerTool("scan_website", {
+        title: "Scan Website for AI Agent Readiness",
+        description: "Trigger a new scan of a website for AI agent readiness. The scan runs asynchronously and typically takes 15-30 seconds. If a recent scan exists (within 1 hour), returns cached results. Use get_scan_results to poll for completed results.",
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+        inputSchema: z.object({
+            url: z
+                .string()
+                .min(1)
+                .describe("The full URL to scan (must be http:// or https://)"),
+        }),
+    }, async ({ url }) => {
+        try {
+            const result = await client.createScan(url);
+            if (isScanCompleted(result)) {
+                return toTextResult(`Recent scan found (cached):\n\n${formatScanResult(result)}`, { type: "cached_result", ...result });
+            }
+            return toTextResult([
+                `Scan enqueued for ${result.domain}`,
+                `Status: ${result.status}`,
+                `ID: ${result.id}`,
+                "message" in result ? `Message: ${result.message}` : "",
+                "",
+                `Poll with get_scan_results for domain "${result.domain}" to check when results are ready.`,
+            ]
+                .filter(Boolean)
+                .join("\n"), { type: "enqueued", id: result.id, domain: result.domain, status: result.status });
+        }
+        catch (error) {
+            return toErrorResult(error);
+        }
+    });
+    server.registerTool("get_scan_results", {
+        title: "Get Scan Results",
+        description: "Get the latest scan results for a domain, including overall score, letter grade, per-category breakdowns, and individual checkpoint results with actionable recommendations. Returns a pending status if the scan is still in progress.",
+        annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+        inputSchema: z.object({
+            domain: z
+                .string()
+                .min(1)
+                .describe("The domain to get scan results for (e.g., example.com)"),
+        }),
+    }, async ({ domain }) => {
+        try {
+            const result = await client.getScanResults(domain);
+            if (!isScanCompleted(result)) {
+                const message = "message" in result ? String(result.message) : "";
+                return toTextResult([
+                    `Scan for ${result.domain} is ${result.status}.`,
+                    message,
+                    "",
+                    "Poll again in a few seconds to check for completion.",
+                ]
+                    .filter(Boolean)
+                    .join("\n"), { type: "pending", id: result.id, domain: result.domain, status: result.status });
+            }
+            return toTextResult(formatScanResult(result), { type: "completed", ...result });
+        }
+        catch (error) {
+            return toErrorResult(error);
+        }
+    });
+};

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+export interface Checkpoint {
+    id: string;
+    name: string;
+    status: "pass" | "partial" | "fail" | "skip";
+    score: number;
+    max_score: number;
+    details: string;
+    recommendation: string;
+    why: string;
+    code_example?: string;
+}
+export interface Category {
+    category: "discovery" | "structured_data" | "semantics" | "agent_protocols" | "security";
+    label: string;
+    score: number;
+    max_score: number;
+    weight: number;
+    checkpoints: Checkpoint[];
+}
+export interface ScanResult {
+    id: string;
+    domain: string;
+    status: "completed" | "failed";
+    overall_score: number;
+    letter_grade: "F" | "D" | "C" | "B" | "A" | "A+";
+    scan_duration_ms: number;
+    completed_at: string;
+    categories: Category[];
+}
+export interface ScanPending {
+    id: string;
+    domain: string;
+    status: "pending" | "running";
+    message: string;
+}
+export interface ScanEnqueued {
+    id: string;
+    domain: string;
+    status: "pending" | "running";
+    poll_url: string;
+    message: string;
+}
+export interface RankingsResponse {
+    entries: ScanResult[];
+    total: number;
+    page: number;
+    per_page: number;
+    total_pages: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/update-checker.d.ts

@@ -0,0 +1,2 @@
+export declare const isNewerVersion: (latest: string, current: string) => boolean;
+export declare const checkForUpdate: (packageName: string, currentVersion: string) => Promise<void>;

package/dist/update-checker.js

@@ -0,0 +1,26 @@
+export const isNewerVersion = (latest, current) => {
+    const l = latest.split(".").map(Number);
+    const c = current.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((l[i] ?? 0) > (c[i] ?? 0))
+            return true;
+        if ((l[i] ?? 0) < (c[i] ?? 0))
+            return false;
+    }
+    return false;
+};
+export const checkForUpdate = async (packageName, currentVersion) => {
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
+        if (!response.ok)
+            return;
+        const data = (await response.json());
+        if (isNewerVersion(data.version, currentVersion)) {
+            process.stderr.write(`\n  Update available: ${currentVersion} → ${data.version}\n` +
+                `  Run: npm install -g ${packageName}@latest\n\n`);
+        }
+    }
+    catch {
+        // Best-effort — silently ignore network errors
+    }
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "isagentready-mcp",
+  "version": "0.2.0",
+  "packageManager": "pnpm@10.28.1",
+  "description": "MCP server for scanning websites for AI agent readiness via the IsAgentReady API",
+  "type": "module",
+  "bin": {
+    "isagentready-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "start": "node --enable-source-maps dist/index.js",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm build",
+    "release": "GITHUB_TOKEN=$(gh auth token) release-it"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bartwaardenburg/isagentready-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "isagentready",
+    "ai-readiness",
+    "website-scanner",
+    "agent-readiness",
+    "model-context-protocol",
+    "automation",
+    "ai",
+    "claude",
+    "llm"
+  ],
+  "author": "Bart Waardenburg",
+  "license": "MIT",
+  "mcpName": "io.github.BartWaardenburg/isagentready-mcp",
+  "bugs": {
+    "url": "https://github.com/bartwaardenburg/isagentready-mcp/issues"
+  },
+  "homepage": "https://github.com/bartwaardenburg/isagentready-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@release-it/conventional-changelog": "^10.0.5",
+    "@types/node": "^20.19.30",
+    "@vitest/coverage-v8": "^4.0.18",
+    "release-it": "^19.2.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.2",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}