@expcat/tigercat-mcp 2.0.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yizhe Wang
+
+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/dist/index.d.ts

@@ -0,0 +1,161 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+type TigercatFramework = 'react' | 'vue';
+interface TigercatMcpOptions {
+    root?: string;
+}
+interface ReferenceSource {
+    path: string;
+    reason: string;
+    truncated: boolean;
+    text?: string;
+}
+interface ComponentReferences {
+    componentIndex: string;
+    props: string;
+    examples: string;
+    react: string;
+    vue: string;
+}
+interface ComponentMetadata {
+    name: string;
+    aliases: string[];
+    category: string;
+    slug: string;
+    testGroup: string;
+    packageSubpath: string;
+    packageTarget: string;
+    typeSource: string;
+    sourceFiles: string[];
+    propsInterfaces: string[];
+    frameworks: TigercatFramework[];
+    references: ComponentReferences;
+}
+interface TopicMetadata {
+    title: string;
+    references: string[];
+    keywords: string[];
+}
+interface CommandApiMetadata {
+    name: string;
+    title: string;
+    topic: string;
+    references: string[];
+}
+interface TigercatContext7 {
+    url?: string;
+    public_key?: string;
+    generated_by?: string;
+    component_count?: number;
+    reference_paths?: Record<string, unknown>;
+    aliases?: Record<string, string | string[]>;
+    command_apis?: Record<string, CommandApiMetadata>;
+    topics?: Record<string, TopicMetadata>;
+    components?: Record<string, ComponentMetadata>;
+    component_index?: Record<string, {
+        props: string;
+        vue: string;
+        react: string;
+        components: string[];
+        examples: string;
+    }>;
+}
+interface SkillIndex {
+    root: string;
+    context7: TigercatContext7;
+    components: Map<string, ComponentMetadata>;
+    componentsByNormalizedName: Map<string, ComponentMetadata>;
+    aliasTargetsByNormalizedName: Map<string, string[]>;
+    topics: Map<string, TopicMetadata>;
+    allowedReferencePaths: Set<string>;
+}
+interface ComponentRoute {
+    component: ComponentMetadata;
+    sources: ReferenceSource[];
+}
+interface ComponentLookupResult {
+    query: string;
+    found: boolean;
+    matches: ComponentRoute[];
+    candidates: SearchResult[];
+}
+interface SearchResult {
+    kind: 'component' | 'alias' | 'category' | 'topic' | 'command';
+    name: string;
+    score: number;
+    reason: string;
+    component?: ComponentMetadata;
+    components?: ComponentMetadata[];
+    topic?: string;
+}
+interface SearchResponse {
+    query: string;
+    framework?: TigercatFramework;
+    results: SearchResult[];
+}
+interface TopicRoute {
+    slug: string;
+    title: string;
+    sources: ReferenceSource[];
+}
+interface TaskRouteResult {
+    task: string;
+    framework?: TigercatFramework;
+    intent: 'component' | 'topic' | 'mixed' | 'unknown';
+    matches: ComponentRoute[];
+    topics: TopicRoute[];
+    candidates: SearchResult[];
+    sources: ReferenceSource[];
+}
+interface InventorySummary {
+    componentCount: number;
+    categories: Array<{
+        slug: string;
+        name: string;
+        count: number;
+    }>;
+    aliases: Record<string, string[]>;
+    topics: Record<string, {
+        title: string;
+        keywords: string[];
+    }>;
+    components: ComponentMetadata[];
+}
+interface DoctorResult {
+    ok: boolean;
+    root: string;
+    componentCount: number;
+    aliasCount: number;
+    topicCount: number;
+    readableReferenceCount: number;
+    issues: string[];
+}
+
+declare function createTigercatMcpServer(options?: TigercatMcpOptions): Server;
+
+declare function loadSkillIndex(root?: string): Promise<SkillIndex>;
+declare function diagnoseTigercatMcp(root?: string): Promise<DoctorResult>;
+
+interface RouteTaskInput {
+    task: string;
+    framework?: TigercatFramework;
+    maxBytes?: number;
+    limit?: number;
+}
+interface ComponentInput {
+    component: string;
+    framework?: TigercatFramework;
+    maxBytes?: number;
+}
+interface SearchInput {
+    query: string;
+    framework?: TigercatFramework;
+    limit?: number;
+}
+declare function searchTigercat(index: SkillIndex, input: SearchInput): Promise<SearchResponse>;
+declare function getTigercatComponent(index: SkillIndex, input: ComponentInput): Promise<ComponentLookupResult>;
+declare function routeTigercatTask(index: SkillIndex, input: RouteTaskInput): Promise<TaskRouteResult>;
+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 };

package/dist/index.js

@@ -0,0 +1,896 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import { resolve, join, relative, isAbsolute, dirname } 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 { existsSync } from 'fs';
+import { access, readFile, realpath, readdir } from 'fs/promises';
+
+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());
+  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 components = buildComponentMap(context7);
+  const componentsByNormalizedName = /* @__PURE__ */ new Map();
+  const aliasTargetsByNormalizedName = /* @__PURE__ */ new Map();
+  for (const [alias, targets] of Object.entries(context7.aliases ?? {})) {
+    addAliasTarget(
+      aliasTargetsByNormalizedName,
+      alias,
+      Array.isArray(targets) ? targets : [targets]
+    );
+  }
+  for (const entry of components.values()) {
+    componentsByNormalizedName.set(normalizeName(entry.name), entry);
+    for (const alias of entry.aliases) {
+      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,
+    context7,
+    components,
+    componentsByNormalizedName,
+    aliasTargetsByNormalizedName,
+    topics: new Map(Object.entries(context7.topics ?? {})),
+    allowedReferencePaths
+  };
+}
+async function diagnoseTigercatMcp(root) {
+  const index = await loadSkillIndex(root);
+  const issues = [];
+  let readableReferenceCount = 0;
+  if (index.context7.component_count !== void 0 && index.context7.component_count !== index.components.size) {
+    issues.push(
+      `context7 component_count ${index.context7.component_count} does not match ${index.components.size}`
+    );
+  }
+  for (const [alias, targets] of index.aliasTargetsByNormalizedName) {
+    const missing = targets.filter((target) => !index.components.has(target));
+    if (missing.length > 0) {
+      issues.push(`alias ${alias} targets missing component(s): ${missing.join(", ")}`);
+    }
+  }
+  for (const path of index.allowedReferencePaths) {
+    try {
+      await access(join(index.root, path));
+      readableReferenceCount += 1;
+    } catch {
+      issues.push(`reference is not readable: ${path}`);
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    root: index.root,
+    componentCount: index.components.size,
+    aliasCount: index.aliasTargetsByNormalizedName.size,
+    topicCount: index.topics.size,
+    readableReferenceCount,
+    issues
+  };
+}
+async function readReferenceSource(index, path, reason, maxBytes = DEFAULT_MAX_BYTES) {
+  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 limit = Number.isFinite(maxBytes) && maxBytes > 0 ? Math.floor(maxBytes) : DEFAULT_MAX_BYTES;
+  const truncated = Buffer.byteLength(text, "utf8") > limit;
+  return {
+    path: normalizedPath,
+    reason,
+    truncated,
+    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;
+    }
+    const next = dirname(current);
+    if (next === current) {
+      throw new Error(`Could not find Tigercat repo root from ${startDirectory}`);
+    }
+    current = next;
+  }
+}
+function normalizeName(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function normalizeRelativePath(path) {
+  const normalized = path.replaceAll("\\", "/").replace(/^\.?\//, "");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.some((part) => part === "..")) {
+    throw new Error(`Reference path may not contain parent segments: ${path}`);
+  }
+  return parts.join("/");
+}
+function buildComponentMap(context7) {
+  const components = /* @__PURE__ */ new Map();
+  for (const entry of Object.values(context7.components ?? {})) {
+    components.set(entry.name, {
+      ...entry,
+      aliases: entry.aliases ?? [],
+      sourceFiles: entry.sourceFiles ?? [],
+      propsInterfaces: entry.propsInterfaces ?? [],
+      frameworks: entry.frameworks ?? ["react", "vue"]
+    });
+  }
+  if (components.size > 0) return components;
+  for (const [slug, entry] of Object.entries(context7.component_index ?? {})) {
+    for (const component of entry.components ?? []) {
+      components.set(component, {
+        name: component,
+        aliases: [],
+        category: toCategoryName(slug),
+        slug,
+        testGroup: slug,
+        packageSubpath: `./${component}`,
+        packageTarget: component,
+        typeSource: "unknown",
+        sourceFiles: [],
+        propsInterfaces: [],
+        frameworks: ["react", "vue"],
+        references: {
+          componentIndex: DEFAULT_COMPONENT_INDEX,
+          props: entry.props,
+          examples: entry.examples,
+          react: entry.react || DEFAULT_REACT_REFERENCE,
+          vue: entry.vue || DEFAULT_VUE_REFERENCE
+        }
+      });
+    }
+  }
+  return components;
+}
+function collectReferencePaths(value) {
+  if (typeof value === "string") {
+    return value.startsWith("skills/tigercat/") ? [value] : [];
+  }
+  if (!value || typeof value !== "object") return [];
+  if (Array.isArray(value)) return value.flatMap((item) => collectReferencePaths(item));
+  return Object.values(value).flatMap((item) => collectReferencePaths(item));
+}
+function addAliasTarget(targetsByAlias, alias, targets) {
+  const normalizedAlias = normalizeName(alias);
+  if (!normalizedAlias) return;
+  const existing = targetsByAlias.get(normalizedAlias) ?? [];
+  targetsByAlias.set(normalizedAlias, [.../* @__PURE__ */ new Set([...existing, ...targets])]);
+}
+async function collectMarkdownReferences(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const paths = [];
+  for (const entry of entries) {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      paths.push(...await collectMarkdownReferences(path));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+function truncateUtf8(text, maxBytes) {
+  const bytes = Buffer.from(text, "utf8");
+  if (bytes.byteLength <= maxBytes) return text;
+  return bytes.subarray(0, maxBytes).toString("utf8").replace(/\uFFFD$/u, "");
+}
+function toCategoryName(slug) {
+  return slug.charAt(0).toUpperCase() + slug.slice(1);
+}
+
+// src/router.ts
+var SKILL_INDEX = "skills/tigercat/SKILL.md";
+var SHARED_PATTERNS = "skills/tigercat/references/shared/patterns/common.md";
+var SHARED_GLOSSARY = "skills/tigercat/references/shared/glossary.md";
+var DEFAULT_LIMIT = 8;
+async function searchTigercat(index, input) {
+  const query = input.query?.trim();
+  if (!query) throw new Error("tigercat_search requires a non-empty query");
+  return {
+    query,
+    framework: input.framework,
+    results: findSearchResults(index, query, input.limit)
+  };
+}
+async function getTigercatComponent(index, input) {
+  const query = input.component?.trim();
+  if (!query) throw new Error("tigercat_component requires a non-empty component");
+  const components = resolveComponentQuery(index, query);
+  if (components.length === 0) {
+    return {
+      query,
+      found: false,
+      matches: [],
+      candidates: findSearchResults(index, query, DEFAULT_LIMIT).filter(
+        (result) => result.kind === "component" || result.kind === "alias"
+      )
+    };
+  }
+  return {
+    query,
+    found: true,
+    matches: await Promise.all(
+      components.map((entry) => createComponentRoute(index, entry, input.framework, input.maxBytes))
+    ),
+    candidates: []
+  };
+}
+async function routeTigercatTask(index, input) {
+  const task = input.task?.trim();
+  if (!task) throw new Error("tigercat_route requires a non-empty task");
+  const mentionedComponents = findMentionedComponents(index, task);
+  const topicMatches = findTopicMatches(index, task);
+  const matches = await Promise.all(
+    mentionedComponents.map(
+      (entry) => createComponentRoute(index, entry, input.framework, input.maxBytes)
+    )
+  );
+  const topics = await Promise.all(
+    topicMatches.map((topic) => createTopicRoute(index, topic.slug, input.maxBytes))
+  );
+  const sources = mergeSources([
+    ...matches.flatMap((match) => match.sources),
+    ...topics.flatMap((topic) => topic.sources)
+  ]);
+  if (matches.length > 0 || topics.length > 0) {
+    return {
+      task,
+      framework: input.framework,
+      intent: matches.length > 0 && topics.length > 0 ? "mixed" : matches.length > 0 ? "component" : "topic",
+      matches,
+      topics,
+      candidates: [],
+      sources
+    };
+  }
+  return {
+    task,
+    framework: input.framework,
+    intent: "unknown",
+    matches: [],
+    topics: [],
+    candidates: findSearchResults(index, task, input.limit),
+    sources: [
+      await readReferenceSource(
+        index,
+        SKILL_INDEX,
+        "Top-level skill route index for choosing the next reference.",
+        input.maxBytes
+      )
+    ]
+  };
+}
+async function createComponentRoute(index, entry, framework, maxBytes) {
+  const sourceSpecs = [
+    {
+      path: entry.references.componentIndex,
+      reason: "Canonical generated component inventory and package subpath map."
+    },
+    {
+      path: entry.references.props,
+      reason: `${entry.name} props, events, methods, and type source.`
+    },
+    { path: entry.references.examples, reason: `${entry.name} compact Vue/React example routes.` },
+    ...framework ? [
+      {
+        path: entry.references[framework],
+        reason: `${framework} binding and import notes.`
+      }
+    ] : [
+      { 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)
+    )
+  );
+  return {
+    component: entry,
+    sources
+  };
+}
+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) => ({
+        path,
+        reason: `${topic.title} reference.`
+      }))
+    ]).map((spec) => readReferenceSource(index, spec.path, spec.reason, maxBytes))
+  );
+  return {
+    slug,
+    title: topic.title,
+    sources
+  };
+}
+function getInventory(index) {
+  const categories = /* @__PURE__ */ new Map();
+  for (const component of index.components.values()) {
+    const current = categories.get(component.slug) ?? {
+      slug: component.slug,
+      name: component.category,
+      count: 0
+    };
+    current.count += 1;
+    categories.set(component.slug, current);
+  }
+  return {
+    componentCount: index.components.size,
+    categories: [...categories.values()].sort((a, b) => a.slug.localeCompare(b.slug)),
+    aliases: Object.fromEntries(
+      [...index.aliasTargetsByNormalizedName.entries()].map(([alias, targets]) => [alias, targets])
+    ),
+    topics: Object.fromEntries(
+      [...index.topics.entries()].map(([slug, topic]) => [
+        slug,
+        { title: topic.title, keywords: topic.keywords }
+      ])
+    ),
+    components: [...index.components.values()]
+  };
+}
+function getCategoryComponents(index, slugOrCategory) {
+  const normalized = normalizeName(slugOrCategory);
+  return [...index.components.values()].filter(
+    (component) => normalizeName(component.slug) === normalized || normalizeName(component.category) === normalized
+  ).sort((a, b) => a.name.localeCompare(b.name));
+}
+function resolveComponentQuery(index, query) {
+  const normalizedQuery = normalizeName(query);
+  const exact = index.componentsByNormalizedName.get(normalizedQuery);
+  if (exact) return [exact];
+  const aliasTargets = index.aliasTargetsByNormalizedName.get(normalizedQuery);
+  if (aliasTargets) return resolveTargetNames(index, aliasTargets);
+  const tokens = query.split(/[^A-Za-z0-9]+/).map((token) => normalizeName(token)).filter(Boolean);
+  const matches = tokens.flatMap((token) => {
+    const tokenExact = index.componentsByNormalizedName.get(token);
+    if (tokenExact) return [tokenExact];
+    const tokenAlias = index.aliasTargetsByNormalizedName.get(token);
+    return tokenAlias ? resolveTargetNames(index, tokenAlias) : [];
+  });
+  return uniqueComponents(matches);
+}
+function findMentionedComponents(index, task) {
+  const normalizedTask = normalizeName(task);
+  const matches = [];
+  for (const [alias, targets] of index.aliasTargetsByNormalizedName) {
+    if (!normalizedTask.includes(alias)) continue;
+    matches.push(...resolveTargetNames(index, targets));
+  }
+  for (const [normalizedName, component] of index.componentsByNormalizedName) {
+    if (normalizedTask.includes(normalizedName)) matches.push(component);
+  }
+  return uniqueComponents(matches).sort((a, b) => b.name.length - a.name.length);
+}
+function findTopicMatches(index, task) {
+  const normalizedTask = normalizeName(task);
+  const matches = [];
+  for (const [slug, topic] of index.topics) {
+    let score = 0;
+    if (normalizedTask.includes(normalizeName(slug))) score += 6;
+    for (const keyword of topic.keywords) {
+      if (keywordMatches(task, normalizedTask, keyword)) score += 4;
+    }
+    if (score > 0) matches.push({ slug, score });
+  }
+  return matches.sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
+}
+function findSearchResults(index, query, limit = DEFAULT_LIMIT) {
+  const normalizedQuery = normalizeName(query);
+  if (!normalizedQuery) return [];
+  const results = [];
+  for (const component of index.components.values()) {
+    const normalizedName = normalizeName(component.name);
+    let score = 0;
+    if (normalizedName === normalizedQuery) score += 100;
+    if (normalizedName.startsWith(normalizedQuery)) score += 70;
+    if (normalizedName.includes(normalizedQuery) || normalizedQuery.includes(normalizedName)) {
+      score += 45;
+    }
+    if (normalizeName(component.category) === normalizedQuery || component.slug === normalizedQuery) {
+      score += 35;
+    }
+    if (component.aliases.some((alias) => normalizeName(alias).includes(normalizedQuery))) {
+      score += 35;
+    }
+    if (score > 0) {
+      results.push({
+        kind: "component",
+        name: component.name,
+        score,
+        reason: `${component.category} component`,
+        component
+      });
+    }
+  }
+  for (const [alias, targets] of index.aliasTargetsByNormalizedName) {
+    if (!alias.includes(normalizedQuery) && !normalizedQuery.includes(alias)) continue;
+    const components = resolveTargetNames(index, targets);
+    results.push({
+      kind: "alias",
+      name: alias,
+      score: alias === normalizedQuery ? 95 : 55,
+      reason: `Alias for ${targets.join(", ")}`,
+      components
+    });
+  }
+  for (const category of getInventory(index).categories) {
+    const normalizedCategory = normalizeName(category.name);
+    if (!normalizedCategory.includes(normalizedQuery) && !category.slug.includes(normalizedQuery)) {
+      continue;
+    }
+    results.push({
+      kind: "category",
+      name: category.slug,
+      score: category.slug === normalizedQuery ? 80 : 40,
+      reason: `${category.count} ${category.name} components`,
+      components: getCategoryComponents(index, category.slug)
+    });
+  }
+  for (const topic of findTopicMatches(index, query)) {
+    const metadata = index.topics.get(topic.slug);
+    if (!metadata) continue;
+    results.push({
+      kind: topic.slug === "commandApis" ? "command" : "topic",
+      name: topic.slug,
+      score: topic.score,
+      reason: metadata.title,
+      topic: topic.slug
+    });
+  }
+  return results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name)).slice(0, Math.max(1, Math.floor(limit)));
+}
+function resolveTargetNames(index, names) {
+  const components = names.flatMap((name) => {
+    const component = index.components.get(name);
+    return component ? [component] : [];
+  });
+  return uniqueComponents(components);
+}
+function uniqueComponents(components) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const component of components) {
+    if (seen.has(component.name)) continue;
+    seen.add(component.name);
+    result.push(component);
+  }
+  return result;
+}
+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);
+    result.push(item);
+  }
+  return result;
+}
+function mergeSources(sources) {
+  return dedupeByPath(sources);
+}
+function keywordMatches(task, normalizedTask, keyword) {
+  const normalizedKeyword = normalizeName(keyword);
+  if (normalizedKeyword) return normalizedTask.includes(normalizedKeyword);
+  return task.toLowerCase().includes(keyword.toLowerCase());
+}
+
+// src/server.ts
+var JSON_MIME = "application/json";
+var MARKDOWN_MIME = "text/markdown";
+function createTigercatMcpServer(options = {}) {
+  const server = new Server(
+    {
+      name: "@expcat/tigercat-mcp",
+      version: "2.0.0-rc.1"
+    },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {}
+      }
+    }
+  );
+  let indexPromise;
+  const getIndex = () => {
+    indexPromise ??= loadSkillIndex(options.root);
+    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(CallToolRequestSchema, async (request) => {
+    const index = await getIndex();
+    const args = request.params.arguments ?? {};
+    try {
+      if (request.params.name === "tigercat_search") {
+        return jsonContent(
+          await searchTigercat(index, {
+            query: stringArg(args.query),
+            framework: frameworkArg(args.framework),
+            limit: numberArg(args.limit)
+          })
+        );
+      }
+      if (request.params.name === "tigercat_component") {
+        return jsonContent(
+          await getTigercatComponent(index, {
+            component: stringArg(args.component),
+            framework: frameworkArg(args.framework),
+            maxBytes: numberArg(args.maxBytes)
+          })
+        );
+      }
+      if (request.params.name === "tigercat_route") {
+        return jsonContent(
+          await routeTigercatTask(index, {
+            task: stringArg(args.task),
+            framework: frameworkArg(args.framework),
+            maxBytes: numberArg(args.maxBytes),
+            limit: numberArg(args.limit)
+          })
+        );
+      }
+      if (request.params.name === "tigercat_reference") {
+        return jsonContent(
+          await readReferenceSource(
+            index,
+            stringArg(args.path),
+            "Direct allow-listed skill reference read.",
+            numberArg(args.maxBytes)
+          )
+        );
+      }
+      throw new Error(`Unknown Tigercat MCP tool: ${request.params.name}`);
+    } catch (error) {
+      return jsonContent({ error: formatError(error) }, true);
+    }
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [
+      {
+        uri: "tigercat://inventory",
+        name: "Tigercat inventory",
+        description: "Generated component, alias, category, and topic inventory.",
+        mimeType: JSON_MIME
+      }
+    ]
+  }));
+  server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+    resourceTemplates: [
+      {
+        uriTemplate: "tigercat://component/{name}",
+        name: "Tigercat component bundle",
+        description: "Component metadata plus props/examples/framework reference bundle.",
+        mimeType: JSON_MIME
+      },
+      {
+        uriTemplate: "tigercat://category/{slug}",
+        name: "Tigercat category inventory",
+        description: "Components in a generated component category.",
+        mimeType: JSON_MIME
+      },
+      {
+        uriTemplate: "tigercat://topic/{topic}",
+        name: "Tigercat topic bundle",
+        description: "Hand-written topic route plus reference snippets.",
+        mimeType: JSON_MIME
+      },
+      {
+        uriTemplate: "tigercat://reference/{path}",
+        name: "Tigercat skill reference",
+        description: "Allow-listed skill reference content.",
+        mimeType: MARKDOWN_MIME
+      }
+    ]
+  }));
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const index = await getIndex();
+    const uri = request.params.uri;
+    if (uri === "tigercat://inventory") {
+      return resourceText(uri, JSON.stringify(getInventory(index), null, 2), 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);
+    }
+    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);
+    }
+    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);
+    }
+    if (uri.startsWith("tigercat://reference/")) {
+      const path = decodeURIComponent(uri.slice("tigercat://reference/".length));
+      const source = await readReferenceSource(index, path, "Direct resource reference read.");
+      return resourceText(uri, source.text ?? "", MARKDOWN_MIME);
+    }
+    throw new Error(`Unknown Tigercat MCP resource: ${uri}`);
+  });
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [
+      {
+        name: "tigercat-usage",
+        description: "Guide an LLM to route, read, and answer a Tigercat usage task.",
+        arguments: [
+          {
+            name: "task",
+            description: "Usage, migration, implementation, or debugging task.",
+            required: true
+          },
+          {
+            name: "framework",
+            description: "Target framework: react or vue.",
+            required: false
+          }
+        ]
+      }
+    ]
+  }));
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name !== "tigercat-usage") {
+      throw new Error(`Unknown Tigercat MCP prompt: ${request.params.name}`);
+    }
+    const args = request.params.arguments ?? {};
+    const task = stringArg(args.task);
+    const framework = optionalStringArg(args.framework) ?? "react or vue";
+    return {
+      description: "Route Tigercat usage references before answering.",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            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.",
+              `Task: ${task}`,
+              "Answer with exact import paths, key props/events, and React/Vue binding differences."
+            ].join("\n")
+          }
+        }
+      ]
+    };
+  });
+  return server;
+}
+function jsonContent(value, isError = false) {
+  return {
+    isError,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(value, null, 2)
+      }
+    ]
+  };
+}
+function resourceText(uri, text, mimeType) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType,
+        text
+      }
+    ]
+  };
+}
+function stringArg(value) {
+  if (typeof value !== "string") {
+    throw new Error("Expected string argument");
+  }
+  return value;
+}
+function optionalStringArg(value) {
+  if (value === void 0) return void 0;
+  return stringArg(value);
+}
+function frameworkArg(value) {
+  if (value === void 0) return void 0;
+  if (value === "react" || value === "vue") return value;
+  throw new Error("framework must be react or vue");
+}
+function numberArg(value) {
+  if (value === void 0) return void 0;
+  if (typeof value === "number") return value;
+  throw new Error("Expected number argument");
+}
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/index.ts
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(helpText());
+    return;
+  }
+  if (options.doctor) {
+    const result = await diagnoseTigercatMcp(options.root);
+    console.log(
+      [
+        `Tigercat MCP doctor: ${result.ok ? "ok" : "failed"}`,
+        `root: ${result.root}`,
+        `components: ${result.componentCount}`,
+        `aliases: ${result.aliasCount}`,
+        `topics: ${result.topicCount}`,
+        `readable references: ${result.readableReferenceCount}`,
+        ...result.issues.map((issue) => `- ${issue}`)
+      ].join("\n")
+    );
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  const server = createTigercatMcpServer({ root: options.root });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+function parseArgs(args) {
+  let root;
+  let help = false;
+  let doctor = false;
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+    if (arg === "--doctor") {
+      doctor = true;
+      continue;
+    }
+    if (arg === "--root") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error("Usage: tigercat-mcp --root <repo-root>");
+      }
+      root = resolve(value);
+      index++;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+  return { root, help, doctor };
+}
+function helpText() {
+  return [
+    "Usage: tigercat-mcp [--root <repo-root>] [--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.",
+    "",
+    "Example MCP client command:",
+    "  tigercat-mcp --root /path/to/Tigercat"
+  ].join("\n");
+}
+var isDirectRun = process.argv[1] !== void 0 && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+if (isDirectRun) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}
+
+export { createTigercatMcpServer, diagnoseTigercatMcp, getCategoryComponents, getInventory, getTigercatComponent, loadSkillIndex, routeTigercatTask, searchTigercat };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@expcat/tigercat-mcp",
+  "version": "2.0.0-rc.2",
+  "type": "module",
+  "description": "Local MCP server for routing LLMs to Tigercat skill references",
+  "license": "MIT",
+  "author": "Yizhe Wang",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/expcat/Tigercat",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/expcat/Tigercat#readme",
+  "bugs": {
+    "url": "https://github.com/expcat/Tigercat/issues"
+  },
+  "keywords": [
+    "tigercat",
+    "mcp",
+    "llm",
+    "skill",
+    "docs"
+  ],
+  "bin": {
+    "tigercat-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
+    "clean": "node ../../scripts/rimraf.mjs dist"
+  }
+}