mockzilla_docs_read

Instructions

Implementation Reference

• lib/tools.js:263-283 (registration)

  Registration of mockzilla_docs_read tool in the LOCAL_TOOLS registry, with description, inputSchema (requiring 'topic' string), and handler reference to readTopic.

  mockzilla_docs_read: {
    description:
      "Return the full markdown for one mockzilla doc topic. Use this " +
      "when the user asks a deep question about a specific area " +
      "(middleware, contexts, codegen, config) and you want full " +
      "context. For broader questions or when you don't know the " +
      "right topic, use `mockzilla_docs_search` first.",
    inputSchema: {
      type: "object",
      properties: {
        topic: {
          type: "string",
          description:
            "Topic name from `mockzilla_docs_topics` (e.g. 'middleware', 'usage/portable').",
        },
      },
      required: ["topic"],
      additionalProperties: false,
    },
    handler: readTopic,
  },

• lib/docs.js:46-53 (handler)

  The readTopic handler function — executes the tool logic by validating the topic argument, calling loadTopicText to fetch the markdown content, and returning {topic, content}.

  export async function readTopic(args) {
    const topic = args.topic;
    if (typeof topic !== "string" || topic.length === 0) {
      throw new Error("`topic` must be a non-empty string");
    }
    const text = await loadTopicText(topic);
    return { topic, content: text };
  }

• lib/docs.js:115-132 (helper)

  The loadTopicText helper — fetches the markdown content for a given topic either from the local filesystem (MOCKZILLA_DOCS_DIR) or from GitHub's raw.githubusercontent.com, with a 1-hour TTL cache.

  async function loadTopicText(topic) {
    if (LOCAL_DIR) {
      return await readFile(path.join(LOCAL_DIR, `${topic}.md`), "utf8");
    }
    const cached = contentCache.get(topic);
    if (cached && Date.now() - cached.at < TTL_MS) return cached.text;
  
    const url = RAW_URL(`docs/${topic}.md`);
    const res = await fetch(url);
    if (!res.ok) {
      throw new Error(
        `Topic "${topic}" not found (GitHub returned ${res.status} for ${url})`,
      );
    }
    const text = await res.text();
    contentCache.set(topic, { text, at: Date.now() });
    return text;
  }

• lib/tools.js:270-281 (schema)

  Input schema for mockzilla_docs_read — requires a 'topic' string property (topic name from mockzilla_docs_topics).

  inputSchema: {
    type: "object",
    properties: {
      topic: {
        type: "string",
        description:
          "Topic name from `mockzilla_docs_topics` (e.g. 'middleware', 'usage/portable').",
      },
    },
    required: ["topic"],
    additionalProperties: false,
  },

• lib/tools.js:6-6 (registration)

  Import of readTopic from './docs.js' into tools.js.

  import { readTopic, searchDocs, topicsList } from "./docs.js";