@expcat/tigercat-mcp 2.0.4 → 2.0.19

package/dist/index.d.ts

@@ -2,12 +2,30 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
 type TigercatFramework = 'react' | 'vue';
 interface TigercatMcpOptions {
+    /** 本地 Tigercat 仓库根目录;提供时优先于 baseUrl,走文件系统读取。 */
     root?: string;
+    /** 远程 skills 基地址(GitHub Pages /mcp/ 路由或其镜像);缺省用官方地址。 */
+    baseUrl?: string;
+    /** 远程 fetch 超时毫秒数。 */
+    timeoutMs?: number;
+}
+type LoadSkillIndexOptions = TigercatMcpOptions;
+interface SkillSource {
+    readonly kind: 'fs' | 'http';
+    /** fs: 绝对仓库根目录;http: 规范化(以 / 结尾)的 base URL。 */
+    readonly origin: string;
+    /** 读取 origin 下 repo-relative 路径的 UTF-8 文本;path 需已经 normalizeRelativePath。 */
+    readText(path: string): Promise<string>;
+    /** doctor 可读性探测,不可读时抛错。 */
+    probe(path: string): Promise<void>;
 }
 interface ReferenceSource {
     path: string;
     reason: string;
     truncated: boolean;
+    /** 抽取的 `## <section>` 小节名;整文件读取时缺省。 */
+    section?: string;
+    /** 内联正文;指针型 source(建议每会话经 tigercat_reference 另读一次)不带 text。 */
     text?: string;
 }
 interface ComponentReferences {
@@ -48,6 +66,8 @@ interface TigercatContext7 {
     generated_by?: string;
     component_count?: number;
     reference_paths?: Record<string, unknown>;
+    /** 全部 skill markdown 的仓库相对路径清单(远程模式的 allow-list 契约)。 */
+    skill_files?: string[];
     aliases?: Record<string, string | string[]>;
     command_apis?: Record<string, CommandApiMetadata>;
     topics?: Record<string, TopicMetadata>;
@@ -61,7 +81,9 @@ interface TigercatContext7 {
     }>;
 }
 interface SkillIndex {
+    /** fs: 绝对仓库根目录;http: base URL。与 source.origin 一致,兼容既有读者。 */
     root: string;
+    source: SkillSource;
     context7: TigercatContext7;
     components: Map<string, ComponentMetadata>;
     componentsByNormalizedName: Map<string, ComponentMetadata>;
@@ -124,17 +146,22 @@ interface InventorySummary {
 interface DoctorResult {
     ok: boolean;
     root: string;
+    mode: 'fs' | 'http';
     componentCount: number;
     aliasCount: number;
     topicCount: number;
     readableReferenceCount: number;
+    /** http 模式下 best-effort 读取的远程 version.json 版本。 */
+    remoteVersion?: string;
     issues: string[];
 }
 
 declare function createTigercatMcpServer(options?: TigercatMcpOptions): Server;
 
-declare function loadSkillIndex(root?: string): Promise<SkillIndex>;
-declare function diagnoseTigercatMcp(root?: string): Promise<DoctorResult>;
+declare function loadSkillIndex(options?: string | LoadSkillIndexOptions): Promise<SkillIndex>;
+declare function diagnoseTigercatMcp(options?: string | LoadSkillIndexOptions): Promise<DoctorResult>;
+
+declare const DEFAULT_REMOTE_BASE_URL = "https://expcat.github.io/Tigercat/mcp/";
 
 interface RouteTaskInput {
     task: string;
@@ -158,4 +185,4 @@ declare function routeTigercatTask(index: SkillIndex, input: RouteTaskInput): Pr
 declare function getInventory(index: SkillIndex): InventorySummary;
 declare function getCategoryComponents(index: SkillIndex, slugOrCategory: string): ComponentMetadata[];
 
-export { type ComponentLookupResult, type ComponentMetadata, type ComponentRoute, type DoctorResult, type InventorySummary, type ReferenceSource, type SearchResponse, type SearchResult, type SkillIndex, type TaskRouteResult, type TigercatFramework, type TigercatMcpOptions, createTigercatMcpServer, diagnoseTigercatMcp, getCategoryComponents, getInventory, getTigercatComponent, loadSkillIndex, routeTigercatTask, searchTigercat };
+export { type ComponentLookupResult, type ComponentMetadata, type ComponentRoute, DEFAULT_REMOTE_BASE_URL, type DoctorResult, type InventorySummary, type LoadSkillIndexOptions, type ReferenceSource, type SearchResponse, type SearchResult, type SkillIndex, type SkillSource, type TaskRouteResult, type TigercatFramework, type TigercatMcpOptions, createTigercatMcpServer, diagnoseTigercatMcp, getCategoryComponents, getInventory, getTigercatComponent, loadSkillIndex, routeTigercatTask, searchTigercat };

package/dist/index.js

@@ -1,25 +1,178 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'url';
-import { realpathSync, existsSync } from 'fs';
-import { resolve, join, relative, isAbsolute, dirname } from 'path';
+import { readFileSync, realpathSync, existsSync } from 'fs';
+import { resolve, join, relative, isAbsolute } from 'path';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { access, readFile, realpath, readdir } from 'fs/promises';
+import { readFile, readdir, access, realpath } from 'fs/promises';
 
+var PACKAGE_VERSION = (() => {
+  try {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const version = JSON.parse(raw).version;
+    return typeof version === "string" && version ? version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+})();
+
+// src/source.ts
+var DEFAULT_REMOTE_BASE_URL = "https://expcat.github.io/Tigercat/mcp/";
+var DEFAULT_FETCH_TIMEOUT_MS = 15e3;
+function createFsSource(root) {
+  return {
+    kind: "fs",
+    origin: root,
+    async readText(path) {
+      const rootPath = await realpath(root);
+      const filePath = await realpath(join(root, path));
+      const relativePath = relative(rootPath, filePath);
+      if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
+        throw new Error(`Reference path escapes the Tigercat repo: ${path}`);
+      }
+      return readFile(filePath, "utf8");
+    },
+    async probe(path) {
+      await access(join(root, path));
+    }
+  };
+}
+function createHttpSource(baseUrl, options = {}) {
+  const base = normalizeBaseUrl(baseUrl);
+  const timeoutMs = Number.isFinite(options.timeoutMs) && (options.timeoutMs ?? 0) > 0 ? Math.floor(options.timeoutMs) : DEFAULT_FETCH_TIMEOUT_MS;
+  const cache = /* @__PURE__ */ new Map();
+  const fetchOnce = (url) => fetch(url, {
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: {
+      accept: "text/markdown, application/json;q=0.9, */*;q=0.8",
+      "user-agent": `tigercat-mcp/${PACKAGE_VERSION}`
+    }
+  });
+  const fetchText = async (path) => {
+    const url = new URL(path, base);
+    let response;
+    try {
+      try {
+        response = await fetchOnce(url);
+      } catch (error) {
+        if (error instanceof Error && error.name === "TimeoutError") throw error;
+        response = await fetchOnce(url);
+      }
+    } catch (error) {
+      throw new Error(
+        fetchFailureMessage(url, error instanceof Error ? error.message : String(error)),
+        { cause: error }
+      );
+    }
+    if (!response.ok) {
+      throw new Error(fetchFailureMessage(url, `HTTP ${response.status}`));
+    }
+    return response.text();
+  };
+  const readText = (path) => {
+    let pending = cache.get(path);
+    if (!pending) {
+      pending = fetchText(path);
+      pending.catch(() => cache.delete(path));
+      cache.set(path, pending);
+    }
+    return pending;
+  };
+  return {
+    kind: "http",
+    origin: base,
+    readText,
+    async probe(path) {
+      await readText(path);
+    }
+  };
+}
+function normalizeBaseUrl(input) {
+  let parsed;
+  try {
+    parsed = new URL(input);
+  } catch {
+    throw new Error(`Invalid Tigercat skills base URL: ${input}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Tigercat skills base URL must use http or https: ${input}`);
+  }
+  if (!parsed.pathname.endsWith("/")) {
+    parsed.pathname = `${parsed.pathname}/`;
+  }
+  return parsed.toString();
+}
+function fetchFailureMessage(url, reason) {
+  return `Failed to fetch Tigercat skill source (${reason}): ${url}. Use --root <repo> for local mode, or --base-url <mirror> if GitHub Pages is unreachable.`;
+}
+
+// src/skill-index.ts
 var DEFAULT_MAX_BYTES = 12e3;
-var SKILL_ROOT = "skills/tigercat";
 var REFERENCES_ROOT = "skills/tigercat/references";
 var DEFAULT_COMPONENT_INDEX = "skills/tigercat/references/component-index.md";
 var DEFAULT_REACT_REFERENCE = "skills/tigercat/references/react/index.md";
 var DEFAULT_VUE_REFERENCE = "skills/tigercat/references/vue/index.md";
-async function loadSkillIndex(root) {
-  const resolvedRoot = root ? resolve(root) : await findTigercatRoot(process.cwd());
+async function loadSkillIndex(options) {
+  const resolved = typeof options === "string" ? { root: options } : options ?? {};
+  if (resolved.root) {
+    return loadFsSkillIndex(resolve(resolved.root));
+  }
+  return loadHttpSkillIndex(resolved.baseUrl ?? DEFAULT_REMOTE_BASE_URL, resolved.timeoutMs);
+}
+async function loadFsSkillIndex(resolvedRoot) {
   const contextPath = join(resolvedRoot, "context7.json");
   if (!existsSync(contextPath)) {
     throw new Error(`Missing context7.json under ${resolvedRoot}`);
   }
   const context7 = JSON.parse(await readFile(contextPath, "utf8"));
+  const allowedReferencePaths = collectAllowedReferencePaths(context7);
+  if (existsSync(join(resolvedRoot, REFERENCES_ROOT))) {
+    for (const path of await collectMarkdownReferences(join(resolvedRoot, REFERENCES_ROOT))) {
+      allowedReferencePaths.add(normalizeRelativePath(relative(resolvedRoot, path)));
+    }
+  }
+  retainMarkdownPaths(allowedReferencePaths);
+  for (const path of allowedReferencePaths) {
+    const absolutePath = join(resolvedRoot, path);
+    if (!existsSync(absolutePath)) {
+      throw new Error(`Missing Tigercat skill reference: ${path}`);
+    }
+  }
+  return buildSkillIndex(context7, createFsSource(resolvedRoot), allowedReferencePaths);
+}
+async function loadHttpSkillIndex(baseUrl, timeoutMs) {
+  const source = createHttpSource(baseUrl, { timeoutMs });
+  const raw = await source.readText("context7.json");
+  let context7;
+  try {
+    context7 = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Invalid context7.json from ${source.origin}context7.json: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  }
+  const allowedReferencePaths = retainMarkdownPaths(collectAllowedReferencePaths(context7));
+  return buildSkillIndex(context7, source, allowedReferencePaths);
+}
+function collectAllowedReferencePaths(context7) {
+  const allowedReferencePaths = /* @__PURE__ */ new Set();
+  for (const path of collectReferencePaths(context7)) {
+    allowedReferencePaths.add(normalizeRelativePath(path));
+  }
+  allowedReferencePaths.add("skills/tigercat/SKILL.md");
+  return allowedReferencePaths;
+}
+function retainMarkdownPaths(paths) {
+  for (const path of paths) {
+    if (!path.endsWith(".md")) {
+      paths.delete(path);
+    }
+  }
+  return paths;
+}
+function buildSkillIndex(context7, source, allowedReferencePaths) {
   const components = buildComponentMap(context7);
   const componentsByNormalizedName = /* @__PURE__ */ new Map();
   const aliasTargetsByNormalizedName = /* @__PURE__ */ new Map();
@@ -36,24 +189,9 @@ async function loadSkillIndex(root) {
       addAliasTarget(aliasTargetsByNormalizedName, alias, [entry.name]);
     }
   }
-  const allowedReferencePaths = /* @__PURE__ */ new Set();
-  for (const path of collectReferencePaths(context7)) {
-    allowedReferencePaths.add(normalizeRelativePath(path));
-  }
-  if (existsSync(join(resolvedRoot, REFERENCES_ROOT))) {
-    for (const path of await collectMarkdownReferences(join(resolvedRoot, REFERENCES_ROOT))) {
-      allowedReferencePaths.add(normalizeRelativePath(relative(resolvedRoot, path)));
-    }
-  }
-  allowedReferencePaths.add("skills/tigercat/SKILL.md");
-  for (const path of allowedReferencePaths) {
-    const absolutePath = join(resolvedRoot, path);
-    if (!existsSync(absolutePath)) {
-      throw new Error(`Missing Tigercat skill reference: ${path}`);
-    }
-  }
   return {
-    root: resolvedRoot,
+    root: source.origin,
+    source,
     context7,
     components,
     componentsByNormalizedName,
@@ -62,8 +200,8 @@ async function loadSkillIndex(root) {
     allowedReferencePaths
   };
 }
-async function diagnoseTigercatMcp(root) {
-  const index = await loadSkillIndex(root);
+async function diagnoseTigercatMcp(options) {
+  const index = await loadSkillIndex(options);
   const issues = [];
   let readableReferenceCount = 0;
   if (index.context7.component_count !== void 0 && index.context7.component_count !== index.components.size) {
@@ -79,36 +217,53 @@ async function diagnoseTigercatMcp(root) {
   }
   for (const path of index.allowedReferencePaths) {
     try {
-      await access(join(index.root, path));
+      await index.source.probe(path);
       readableReferenceCount += 1;
     } catch {
       issues.push(`reference is not readable: ${path}`);
     }
   }
+  let remoteVersion;
+  if (index.source.kind === "http") {
+    try {
+      const parsed = JSON.parse(await index.source.readText("version.json"));
+      if (typeof parsed.version === "string" && parsed.version) {
+        remoteVersion = parsed.version;
+      }
+    } catch {
+    }
+  }
   return {
     ok: issues.length === 0,
     root: index.root,
+    mode: index.source.kind,
     componentCount: index.components.size,
     aliasCount: index.aliasTargetsByNormalizedName.size,
     topicCount: index.topics.size,
     readableReferenceCount,
+    ...remoteVersion ? { remoteVersion } : {},
     issues
   };
 }
-async function readReferenceSource(index, path, reason, maxBytes = DEFAULT_MAX_BYTES) {
+async function readReferenceSource(index, path, reason, maxBytes = DEFAULT_MAX_BYTES, section) {
   const normalizedPath = normalizeRelativePath(path);
   if (!index.allowedReferencePaths.has(normalizedPath)) {
     throw new Error(`Reference path is not allowed: ${path}`);
   }
-  const absolutePath = join(index.root, normalizedPath);
-  const rootPath = await realpath(index.root);
-  const filePath = await realpath(absolutePath);
-  const relativePath = relative(rootPath, filePath);
-  if (relativePath.startsWith("..") || isAbsolute(relativePath)) {
-    throw new Error(`Reference path escapes the Tigercat repo: ${path}`);
-  }
-  const text = await readFile(filePath, "utf8");
+  const text = await index.source.readText(normalizedPath);
   const limit = Number.isFinite(maxBytes) && maxBytes > 0 ? Math.floor(maxBytes) : DEFAULT_MAX_BYTES;
+  if (section) {
+    const extracted = extractMarkdownSection(text, section);
+    if (extracted !== void 0) {
+      return {
+        path: normalizedPath,
+        reason,
+        truncated: Buffer.byteLength(extracted, "utf8") > limit,
+        section,
+        text: truncateUtf8(extracted, limit)
+      };
+    }
+  }
   const truncated = Buffer.byteLength(text, "utf8") > limit;
   return {
     path: normalizedPath,
@@ -117,21 +272,37 @@ async function readReferenceSource(index, path, reason, maxBytes = DEFAULT_MAX_B
     text: truncateUtf8(text, limit)
   };
 }
-async function findTigercatRoot(startDirectory) {
-  let current = resolve(startDirectory);
-  while (true) {
-    if (existsSync(join(current, "context7.json")) && existsSync(join(current, SKILL_ROOT))) {
-      return current;
+function extractMarkdownSection(text, section) {
+  const lines = text.split("\n");
+  const heading = section.trim().toLowerCase();
+  let start = -1;
+  for (let index = 0; index < lines.length; index++) {
+    const match = /^##\s+(.+?)\s*$/.exec(lines[index]);
+    if (match && match[1].toLowerCase() === heading) {
+      start = index;
+      break;
     }
-    const next = dirname(current);
-    if (next === current) {
-      throw new Error(`Could not find Tigercat repo root from ${startDirectory}`);
+  }
+  if (start === -1) return void 0;
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index++) {
+    if (/^##\s/.test(lines[index])) {
+      end = index;
+      break;
     }
-    current = next;
   }
+  return `${lines.slice(start, end).join("\n").trimEnd()}
+`;
+}
+function createReferencePointer(index, path, reason) {
+  const normalizedPath = normalizeRelativePath(path);
+  if (!index.allowedReferencePaths.has(normalizedPath)) {
+    throw new Error(`Reference path is not allowed: ${path}`);
+  }
+  return { path: normalizedPath, reason, truncated: false };
 }
 function normalizeName(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return value.toLowerCase().replace(/[^a-z0-9一-鿿]/g, "");
 }
 function normalizeRelativePath(path) {
   const normalized = path.replaceAll("\\", "/").replace(/^\.?\//, "");
@@ -274,8 +445,10 @@ async function routeTigercatTask(index, input) {
       task,
       framework: input.framework,
       intent: matches.length > 0 && topics.length > 0 ? "mixed" : matches.length > 0 ? "component" : "topic",
-      matches,
-      topics,
+      // 正文只在顶层 sources 内联一次;matches/topics 里保留 path/reason 元数据,
+      // 否则同一份 reference 全文会在响应里出现两遍。
+      matches: matches.map((match) => ({ ...match, sources: match.sources.map(stripText) })),
+      topics: topics.map((topic) => ({ ...topic, sources: topic.sources.map(stripText) })),
       candidates: [],
       sources
     };
@@ -298,14 +471,11 @@ async function routeTigercatTask(index, input) {
   };
 }
 async function createComponentRoute(index, entry, framework, maxBytes) {
-  const sourceSpecs = [
-    {
-      path: entry.references.componentIndex,
-      reason: "Canonical generated component inventory and package subpath map."
-    },
+  const inlineSpecs = dedupeByPath([
     {
       path: entry.references.props,
-      reason: `${entry.name} props, events, methods, and type source.`
+      reason: `${entry.name} props, events, methods, and type source.`,
+      section: entry.name
     },
     { path: entry.references.examples, reason: `${entry.name} compact Vue/React example routes.` },
     ...framework ? [
@@ -316,36 +486,60 @@ async function createComponentRoute(index, entry, framework, maxBytes) {
     ] : [
       { path: entry.references.react, reason: "React binding and import notes." },
       { path: entry.references.vue, reason: "Vue binding and import notes." }
-    ],
-    { path: SHARED_PATTERNS, reason: "Cross-framework binding differences and common patterns." },
-    { path: SHARED_GLOSSARY, reason: "Shared Tigercat terminology." }
-  ];
+    ]
+  ]);
   const sources = await Promise.all(
-    dedupeByPath(sourceSpecs).map(
-      (spec) => readReferenceSource(index, spec.path, spec.reason, maxBytes)
+    inlineSpecs.map(
+      (spec) => readReferenceSource(
+        index,
+        spec.path,
+        spec.reason,
+        maxBytes,
+        "section" in spec ? spec.section : void 0
+      )
     )
   );
+  const pointers = [
+    {
+      path: entry.references.componentIndex,
+      reason: "Full component inventory; read at most once per session via tigercat_reference."
+    },
+    {
+      path: SHARED_PATTERNS,
+      reason: "Cross-framework binding differences; read at most once per session via tigercat_reference."
+    },
+    {
+      path: SHARED_GLOSSARY,
+      reason: "Shared Tigercat terminology; read at most once per session via tigercat_reference."
+    }
+  ].map((spec) => createReferencePointer(index, spec.path, spec.reason));
   return {
     component: entry,
-    sources
+    sources: dedupeByPath([...sources, ...pointers])
   };
 }
 async function createTopicRoute(index, slug, maxBytes) {
   const topic = index.topics.get(slug);
   if (!topic) throw new Error(`Unknown Tigercat topic: ${slug}`);
   const sources = await Promise.all(
-    dedupeByPath([
-      { path: SKILL_INDEX, reason: "Top-level skill route index." },
-      ...topic.references.map((path) => ({
+    dedupeByPath(
+      topic.references.map((path) => ({
         path,
         reason: `${topic.title} reference.`
       }))
-    ]).map((spec) => readReferenceSource(index, spec.path, spec.reason, maxBytes))
+    ).map((spec) => readReferenceSource(index, spec.path, spec.reason, maxBytes))
   );
   return {
     slug,
     title: topic.title,
-    sources
+    sources: dedupeByPath([
+      ...sources,
+      createReferencePointer(
+        index,
+        SKILL_INDEX,
+        "Top-level skill route index; read via tigercat_reference only if the topic references are insufficient."
+      )
+    ])
   };
 }
 function getInventory(index) {
@@ -506,8 +700,9 @@ function dedupeByPath(items) {
   const seen = /* @__PURE__ */ new Set();
   const result = [];
   for (const item of items) {
-    if (seen.has(item.path)) continue;
-    seen.add(item.path);
+    const key = `${item.path}#${item.section ?? ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
     result.push(item);
   }
   return result;
@@ -515,6 +710,10 @@ function dedupeByPath(items) {
 function mergeSources(sources) {
   return dedupeByPath(sources);
 }
+function stripText(source) {
+  const { text: _text, ...rest } = source;
+  return rest;
+}
 function keywordMatches(task, normalizedTask, keyword) {
   const normalizedKeyword = normalizeName(keyword);
   if (normalizedKeyword) return normalizedTask.includes(normalizedKeyword);
@@ -524,100 +723,147 @@ function keywordMatches(task, normalizedTask, keyword) {
 // src/server.ts
 var JSON_MIME = "application/json";
 var MARKDOWN_MIME = "text/markdown";
+var TIGERCAT_SERVER_INSTRUCTIONS = [
+  "Tigercat is a Tailwind CSS React + Vue 3 UI library (149 components, imported from",
+  "@expcat/tigercat-react / @expcat/tigercat-vue PascalCase subpaths such as",
+  "@expcat/tigercat-react/Button). Use this server BEFORE writing or reviewing any code",
+  "that touches Tigercat \u2014 it returns exact import subpaths, props/events, and",
+  "per-framework binding notes that differ from generic React/Vue knowledge.",
+  "",
+  "Tool order: call `tigercat_route` first for any natural-language task (always pass",
+  "`framework`; it roughly halves the payload). Call `tigercat_component` when you",
+  "already know the component name or alias. Use `tigercat_search` only for fuzzy",
+  "discovery, and `tigercat_reference` only to read a path that a previous result",
+  "pointed to.",
+  "",
+  "Responses inline the needed reference text once, as extra content blocks after the",
+  'JSON summary. Sources marked `"inlined": false` are session-level background',
+  "(inventory, glossary, patterns): read each at most once per session via",
+  "`tigercat_reference`, and only if actually needed. Do not re-read paths you already",
+  "received.",
+  "",
+  "Component matching works with English names and listed Chinese aliases (e.g. \u8868\u5355,",
+  "\u65E5\u671F\u9009\u62E9\u5668); prefer English component names for precision. `notification` is a",
+  "command API topic, not a component; `Message` is both."
+].join("\n");
+var FRAMEWORK_SCHEMA = {
+  type: "string",
+  enum: ["react", "vue"],
+  description: "Target framework. Omit to receive notes for both React and Vue (larger payload)."
+};
+var MAX_BYTES_SCHEMA = {
+  type: "number",
+  minimum: 200,
+  maximum: 5e4,
+  description: "Byte cap per inlined source (default 12000). Raise only when a source was truncated."
+};
+var TIGERCAT_TOOLS = [
+  {
+    name: "tigercat_search",
+    description: "Fuzzy-search Tigercat components, aliases, categories, topics, and command APIs. Returns ranked name/metadata matches only \u2014 no reference text, cheapest call. Use when unsure of the exact name; otherwise go straight to tigercat_component or tigercat_route.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: 'Component, alias, category, topic, or use case, e.g. "table" or "\u8868\u683C".'
+        },
+        framework: FRAMEWORK_SCHEMA,
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 30,
+          description: "Max results (default 8)."
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "tigercat_component",
+    description: "Look up one Tigercat component by exact name or alias (e.g. Button, Grid, \u65E5\u671F\u9009\u62E9\u5668). Returns its import subpath, its own props/events section, compact category examples, and framework binding notes, inlined as content blocks after the JSON summary. Preferred over tigercat_route when you already know the component name; pass framework to shrink the payload.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        component: {
+          type: "string",
+          description: "Component name or alias, such as Button, Grid, or \u8868\u683C."
+        },
+        framework: FRAMEWORK_SCHEMA,
+        maxBytes: MAX_BYTES_SCHEMA
+      },
+      required: ["component"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "tigercat_route",
+    description: 'Route a natural-language Tigercat task to the smallest useful component/topic references. Preferred FIRST call for any Tigercat coding task. Returns matched components with import paths plus each needed reference inlined exactly once; sources marked "inlined": false are session-level background to read at most once via tigercat_reference. Always pass framework. Name components in English or a listed Chinese alias.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: 'Natural-language Tigercat task, e.g. "add a DatePicker with Form validation" or "\u7ED9\u8868\u5355\u52A0\u65E5\u671F\u9009\u62E9\u5668".'
+        },
+        framework: FRAMEWORK_SCHEMA,
+        maxBytes: MAX_BYTES_SCHEMA,
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 30,
+          description: "Max fallback candidates when nothing matches directly (default 8)."
+        }
+      },
+      required: ["task"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "tigercat_reference",
+    description: 'Read one allow-listed Tigercat skill reference file verbatim. Use only for paths returned by other tigercat tools \u2014 typically to read an "inlined": false pointer source once per session.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: 'Repo-relative path under skills/tigercat/, exactly as returned in a source "path" field, e.g. skills/tigercat/references/shared/glossary.md.'
+        },
+        maxBytes: MAX_BYTES_SCHEMA
+      },
+      required: ["path"],
+      additionalProperties: false
+    }
+  }
+];
 function createTigercatMcpServer(options = {}) {
   const server = new Server(
     {
       name: "@expcat/tigercat-mcp",
-      version: "2.0.0-rc.1"
+      version: PACKAGE_VERSION
     },
     {
       capabilities: {
         tools: {},
         resources: {},
         prompts: {}
-      }
+      },
+      instructions: TIGERCAT_SERVER_INSTRUCTIONS
     }
   );
   let indexPromise;
   const getIndex = () => {
-    indexPromise ??= loadSkillIndex(options.root);
+    indexPromise ??= loadSkillIndex(options);
     return indexPromise;
   };
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-      {
-        name: "tigercat_search",
-        description: "Search Tigercat components, aliases, categories, topics, and command APIs.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: {
-              type: "string",
-              description: "Component, alias, category, topic, or use case."
-            },
-            framework: { type: "string", enum: ["react", "vue"] },
-            limit: { type: "number", minimum: 1, maximum: 30 }
-          },
-          required: ["query"],
-          additionalProperties: false
-        }
-      },
-      {
-        name: "tigercat_component",
-        description: "Return exact Tigercat component metadata, import paths, docs, examples, and framework notes.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            component: {
-              type: "string",
-              description: "Component name or alias, such as Button or Grid."
-            },
-            framework: { type: "string", enum: ["react", "vue"] },
-            maxBytes: { type: "number", minimum: 200, maximum: 5e4 }
-          },
-          required: ["component"],
-          additionalProperties: false
-        }
-      },
-      {
-        name: "tigercat_route",
-        description: "Route a natural-language Tigercat task to the smallest useful component/topic references.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            task: { type: "string", description: "Natural-language Tigercat task." },
-            framework: { type: "string", enum: ["react", "vue"] },
-            maxBytes: { type: "number", minimum: 200, maximum: 5e4 },
-            limit: { type: "number", minimum: 1, maximum: 30 }
-          },
-          required: ["task"],
-          additionalProperties: false
-        }
-      },
-      {
-        name: "tigercat_reference",
-        description: "Read an allow-listed Tigercat skill reference with optional byte truncation.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            path: {
-              type: "string",
-              description: "Repo-relative skill reference path under skills/tigercat."
-            },
-            maxBytes: { type: "number", minimum: 200, maximum: 5e4 }
-          },
-          required: ["path"],
-          additionalProperties: false
-        }
-      }
-    ]
-  }));
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TIGERCAT_TOOLS }));
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const index = await getIndex();
     const args = request.params.arguments ?? {};
     try {
       if (request.params.name === "tigercat_search") {
-        return jsonContent(
+        return renderToolResult(
           await searchTigercat(index, {
             query: stringArg(args.query),
             framework: frameworkArg(args.framework),
@@ -626,7 +872,7 @@ function createTigercatMcpServer(options = {}) {
         );
       }
       if (request.params.name === "tigercat_component") {
-        return jsonContent(
+        return renderToolResult(
           await getTigercatComponent(index, {
             component: stringArg(args.component),
             framework: frameworkArg(args.framework),
@@ -635,7 +881,7 @@ function createTigercatMcpServer(options = {}) {
         );
       }
       if (request.params.name === "tigercat_route") {
-        return jsonContent(
+        return renderToolResult(
           await routeTigercatTask(index, {
             task: stringArg(args.task),
             framework: frameworkArg(args.framework),
@@ -645,7 +891,7 @@ function createTigercatMcpServer(options = {}) {
         );
       }
       if (request.params.name === "tigercat_reference") {
-        return jsonContent(
+        return renderToolResult(
           await readReferenceSource(
             index,
             stringArg(args.path),
@@ -701,22 +947,22 @@ function createTigercatMcpServer(options = {}) {
     const index = await getIndex();
     const uri = request.params.uri;
     if (uri === "tigercat://inventory") {
-      return resourceText(uri, JSON.stringify(getInventory(index), null, 2), JSON_MIME);
+      return resourceText(uri, JSON.stringify(getInventory(index)), JSON_MIME);
     }
     if (uri.startsWith("tigercat://component/")) {
       const component = decodeURIComponent(uri.slice("tigercat://component/".length));
       const lookup = await getTigercatComponent(index, { component });
-      return resourceText(uri, JSON.stringify(lookup, null, 2), JSON_MIME);
+      return resourceText(uri, JSON.stringify(lookup), JSON_MIME);
     }
     if (uri.startsWith("tigercat://category/")) {
       const category = decodeURIComponent(uri.slice("tigercat://category/".length));
       const components = getCategoryComponents(index, category);
-      return resourceText(uri, JSON.stringify({ category, components }, null, 2), JSON_MIME);
+      return resourceText(uri, JSON.stringify({ category, components }), JSON_MIME);
     }
     if (uri.startsWith("tigercat://topic/")) {
       const topic = decodeURIComponent(uri.slice("tigercat://topic/".length));
       const route = await createTopicRoute(index, topic);
-      return resourceText(uri, JSON.stringify(route, null, 2), JSON_MIME);
+      return resourceText(uri, JSON.stringify(route), JSON_MIME);
     }
     if (uri.startsWith("tigercat://reference/")) {
       const path = decodeURIComponent(uri.slice("tigercat://reference/".length));
@@ -762,7 +1008,7 @@ function createTigercatMcpServer(options = {}) {
             text: [
               `Use tigercat_route with framework "${framework}" before answering.`,
               "Use tigercat_component for exact component imports and props when route results mention components.",
-              "Read only the returned sources needed for the task.",
+              'Read only the returned sources; sources marked "inlined": false are optional background \u2014 fetch each at most once via tigercat_reference.',
               `Task: ${task}`,
               "Answer with exact import paths, key props/events, and React/Vue binding differences."
             ].join("\n")
@@ -779,11 +1025,49 @@ function jsonContent(value, isError = false) {
     content: [
       {
         type: "text",
-        text: JSON.stringify(value, null, 2)
+        text: JSON.stringify(value)
       }
     ]
   };
 }
+function renderToolResult(value) {
+  const blocks = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (Array.isArray(node)) return node.map(visit);
+    if (!node || typeof node !== "object") return node;
+    const record = node;
+    if (isReferenceSource(record)) {
+      const { text, ...rest } = record;
+      if (typeof text !== "string") return { ...rest, inlined: false };
+      const section = typeof record.section === "string" ? record.section : void 0;
+      const key = `${record.path}#${section ?? ""}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        blocks.push({
+          type: "text",
+          text: formatSourceBlock(record.path, section, record.truncated, text)
+        });
+      }
+      return { ...rest, inlined: true };
+    }
+    return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, visit(v)]));
+  };
+  const summary = visit(value);
+  return {
+    isError: false,
+    content: [{ type: "text", text: JSON.stringify(summary) }, ...blocks]
+  };
+}
+function isReferenceSource(record) {
+  return typeof record.path === "string" && typeof record.reason === "string" && typeof record.truncated === "boolean";
+}
+function formatSourceBlock(path, section, truncated, text) {
+  const heading = section ? `${path} \xA7 ${section}` : path;
+  const truncatedNote = truncated ? " [truncated: raise maxBytes to read more]" : "";
+  return `===== source: ${heading}${truncatedNote} =====
+${text}`;
+}
 function resourceText(uri, text, mimeType) {
   return {
     contents: [
@@ -821,17 +1105,20 @@ function formatError(error) {
 
 // src/index.ts
 async function main() {
-  const options = parseArgs(process.argv.slice(2));
-  if (options.help) {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
     console.log(helpText());
     return;
   }
-  if (options.doctor) {
-    const result = await diagnoseTigercatMcp(options.root);
+  const options = resolveOptions(parsed);
+  if (parsed.doctor) {
+    const result = await diagnoseTigercatMcp(options);
     console.log(
       [
         `Tigercat MCP doctor: ${result.ok ? "ok" : "failed"}`,
-        `root: ${result.root}`,
+        `mode: ${result.mode === "http" ? "remote" : "local"}`,
+        `${result.mode === "http" ? "base url" : "root"}: ${result.root}`,
+        ...result.remoteVersion ? [`remote version: ${result.remoteVersion}`] : [],
         `components: ${result.componentCount}`,
         `aliases: ${result.aliasCount}`,
         `topics: ${result.topicCount}`,
@@ -842,12 +1129,13 @@ async function main() {
     if (!result.ok) process.exitCode = 1;
     return;
   }
-  const server = createTigercatMcpServer({ root: options.root });
+  const server = createTigercatMcpServer(options);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 function parseArgs(args) {
   let root;
+  let baseUrl;
   let help = false;
   let doctor = false;
   for (let index = 0; index < args.length; index++) {
@@ -869,20 +1157,47 @@ function parseArgs(args) {
       index++;
       continue;
     }
+    if (arg === "--base-url") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Usage: tigercat-mcp --base-url <skills-base-url>");
+      }
+      baseUrl = value;
+      index++;
+      continue;
+    }
     throw new Error(`Unknown argument: ${arg}`);
   }
-  return { root, help, doctor };
+  return { root, baseUrl, help, doctor };
+}
+function resolveOptions(parsed) {
+  if (parsed.root) {
+    if (parsed.baseUrl) {
+      console.error("tigercat-mcp: --root takes precedence over --base-url; ignoring --base-url.");
+    }
+    return { root: parsed.root };
+  }
+  const envBaseUrl = process.env.TIGERCAT_MCP_BASE_URL?.trim();
+  return { baseUrl: parsed.baseUrl ?? (envBaseUrl || void 0) ?? DEFAULT_REMOTE_BASE_URL };
 }
 function helpText() {
   return [
-    "Usage: tigercat-mcp [--root <repo-root>] [--doctor]",
+    "Usage: tigercat-mcp [--root <repo-root>] [--base-url <skills-base-url>] [--doctor]",
     "",
     "Runs the Tigercat skill MCP server over stdio.",
-    "--doctor validates the generated inventory and exits without starting stdio.",
-    "If --root is omitted, the server searches upward from the current directory for context7.json.",
+    `By default skill references are fetched from ${DEFAULT_REMOTE_BASE_URL} (GitHub Pages).`,
+    "",
+    "  --root <repo-root>       read skills from a local Tigercat checkout (dev/offline mode).",
+    "  --base-url <url>         fetch skills from a mirror of the /mcp/ Pages route.",
+    "  --doctor                 validate the skill inventory and exit without starting stdio.",
+    "  TIGERCAT_MCP_BASE_URL    environment fallback for --base-url.",
+    "",
+    "Examples:",
+    "  tigercat-mcp                                   # remote skills (default)",
+    "  tigercat-mcp --root /path/to/Tigercat          # local checkout",
+    "  tigercat-mcp --base-url https://mirror.example.com/mcp/",
     "",
-    "Example MCP client command:",
-    "  tigercat-mcp --root /path/to/Tigercat"
+    "If GitHub Pages is unreachable (offline, proxy, regional block), use --root or --base-url."
   ].join("\n");
 }
 var isDirectRun = (() => {
@@ -900,4 +1215,4 @@ if (isDirectRun) {
   });
 }
 
-export { createTigercatMcpServer, diagnoseTigercatMcp, getCategoryComponents, getInventory, getTigercatComponent, loadSkillIndex, routeTigercatTask, searchTigercat };
+export { DEFAULT_REMOTE_BASE_URL, createTigercatMcpServer, diagnoseTigercatMcp, getCategoryComponents, getInventory, getTigercatComponent, loadSkillIndex, routeTigercatTask, searchTigercat };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@expcat/tigercat-mcp",
-  "version": "2.0.4",
+  "version": "2.0.19",
   "type": "module",
-  "description": "Local MCP server for routing LLMs to Tigercat skill references",
+  "description": "MCP server routing LLMs to Tigercat skill references, fetched from GitHub Pages by default with a local checkout fallback",
   "license": "MIT",
   "author": "Yizhe Wang",
   "repository": {
@@ -10,7 +10,7 @@
     "url": "https://github.com/expcat/Tigercat",
     "directory": "packages/mcp"
   },
-  "homepage": "https://github.com/expcat/Tigercat#readme",
+  "homepage": "https://expcat.github.io/Tigercat/mcp/",
   "bugs": {
     "url": "https://github.com/expcat/Tigercat/issues"
   },