supporthero-mcp-server 1.0.0 → 1.0.2

package/dist/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SupportHeroClient } from "./services/client.js";

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "supporthero-mcp-server",
-  "version": "1.0.0",
-  "description": "MCP server for SupportHero Help Center API (read-only)",
+  "version": "1.0.2",
+  "description": "MCP server for SupportHero Help Center API (read-only). Enables Claude and other LLMs to search, browse, and read help center articles.",
   "type": "module",
   "main": "dist/index.js",
+  "bin": {
+    "supporthero-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/tmp && mv dist/tmp dist/index.js",
     "start": "node dist/index.js",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
@@ -17,4 +25,4 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0"
   }
-}
+}

package/src/constants.ts

@@ -1,5 +0,0 @@
-// SupportHero API base path (domain comes from env var)
-export const API_VERSION = "v1";
-export const DEFAULT_SEARCH_MAX = 10;
-export const MAX_SEARCH_RESULTS = 100;
-export const CHARACTER_LIMIT = 50_000;

package/src/index.ts

@@ -1,49 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { SupportHeroClient } from "./services/client.js";
-import { registerTools } from "./tools/helpCenter.js";
-
-// ── Configuration ───────────────────────────────────────────
-
-const SUPPORTHERO_DOMAIN = process.env.SUPPORTHERO_DOMAIN;
-const SUPPORTHERO_API_KEY = process.env.SUPPORTHERO_API_KEY;
-
-if (!SUPPORTHERO_DOMAIN) {
-  console.error(
-    "Missing SUPPORTHERO_DOMAIN env var. " +
-    "Set it to your Help Center URL, e.g. https://yourcompany.supporthero.io"
-  );
-  process.exit(1);
-}
-
-if (!SUPPORTHERO_API_KEY) {
-  console.error(
-    "Missing SUPPORTHERO_API_KEY env var. " +
-    "Find your API key in SupportHero > Settings (bottom of page)."
-  );
-  process.exit(1);
-}
-
-// ── Server Setup ────────────────────────────────────────────
-
-const server = new McpServer({
-  name: "supporthero-mcp-server",
-  version: "1.0.0",
-});
-
-const client = new SupportHeroClient(SUPPORTHERO_DOMAIN, SUPPORTHERO_API_KEY);
-
-registerTools(server, client);
-
-// ── Transport ───────────────────────────────────────────────
-
-async function main(): Promise<void> {
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error("SupportHero MCP server running on stdio");
-}
-
-main().catch((error) => {
-  console.error("Fatal error:", error);
-  process.exit(1);
-});

package/src/schemas/inputs.ts

@@ -1,85 +0,0 @@
-import { z } from "zod";
-import { MAX_SEARCH_RESULTS, DEFAULT_SEARCH_MAX } from "../constants.js";
-
-// ── Categories ──────────────────────────────────────────────
-
-export const ListCategoriesInputSchema = z
-  .object({
-    parent_category_id: z
-      .string()
-      .optional()
-      .describe(
-        "If provided, returns sub-categories of this category. " +
-        "If omitted, returns all top-level categories."
-      ),
-  })
-  .strict();
-
-export type ListCategoriesInput = z.infer<typeof ListCategoriesInputSchema>;
-
-export const GetCategoryInputSchema = z
-  .object({
-    category_id: z
-      .string()
-      .min(1, "category_id is required")
-      .describe("The ID of the category to retrieve."),
-  })
-  .strict();
-
-export type GetCategoryInput = z.infer<typeof GetCategoryInputSchema>;
-
-// ── Articles ────────────────────────────────────────────────
-
-export const ListArticlesInputSchema = z
-  .object({
-    category_id: z
-      .string()
-      .min(1, "category_id is required")
-      .describe(
-        "The ID of the category whose articles to list. " +
-        "Use supporthero_list_categories first to find category IDs."
-      ),
-  })
-  .strict();
-
-export type ListArticlesInput = z.infer<typeof ListArticlesInputSchema>;
-
-export const GetArticleInputSchema = z
-  .object({
-    article_id: z
-      .string()
-      .min(1, "article_id is required")
-      .describe("The ID of the article to retrieve. Returns full content."),
-  })
-  .strict();
-
-export type GetArticleInput = z.infer<typeof GetArticleInputSchema>;
-
-// ── Search ──────────────────────────────────────────────────
-
-export const SearchArticlesInputSchema = z
-  .object({
-    search_text: z
-      .string()
-      .min(1, "search_text is required")
-      .describe("The search query. Matches against article titles and content."),
-    max: z
-      .number()
-      .int()
-      .min(1)
-      .max(MAX_SEARCH_RESULTS)
-      .default(DEFAULT_SEARCH_MAX)
-      .describe(
-        `Maximum number of results to return per page (1 to ${MAX_SEARCH_RESULTS}, default ${DEFAULT_SEARCH_MAX}).`
-      ),
-    offset: z
-      .string()
-      .optional()
-      .describe(
-        "Pagination cursor from a previous search response. " +
-        "Pass the offset value from the prior result to get the next page."
-      ),
-  })
-  .strict();
-
-export type SearchArticlesInput = z.infer<typeof SearchArticlesInputSchema>;

package/src/services/client.ts

@@ -1,96 +0,0 @@
-import { API_VERSION } from "../constants.js";
-import type {
-  SHCategory,
-  SHCategoryListResponse,
-  SHArticle,
-  SHArticleListResponse,
-  SHSearchResponse,
-} from "../types.js";
-
-/**
- * SupportHero API client.
- * All methods are read-only GET requests against the Help Center API.
- */
-export class SupportHeroClient {
-  private baseUrl: string;
-  private apiKey: string;
-
-  constructor(baseUrl: string, apiKey: string) {
-    // Normalize: strip trailing slash
-    this.baseUrl = baseUrl.replace(/\/+$/, "");
-    this.apiKey = apiKey;
-  }
-
-  /**
-   * Core fetch wrapper. Appends apiKey and handles errors uniformly.
-   */
-  private async request<T>(path: string, params: Record<string, string> = {}): Promise<T> {
-    const url = new URL(`/api/${API_VERSION}/${path}`, this.baseUrl);
-    url.searchParams.set("apiKey", this.apiKey);
-    for (const [key, value] of Object.entries(params)) {
-      if (value !== undefined && value !== "") {
-        url.searchParams.set(key, value);
-      }
-    }
-
-    const response = await fetch(url.toString(), {
-      method: "GET",
-      headers: { "Accept": "application/json" },
-    });
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      throw new Error(
-        `SupportHero API error ${response.status}: ${response.statusText}. ${body}`
-      );
-    }
-
-    return response.json() as Promise<T>;
-  }
-
-  // ── Categories ──────────────────────────────────────────────
-
-  /** List top-level categories, or sub-categories of a given parent. */
-  async listCategories(parentCategoryId?: string): Promise<SHCategory[]> {
-    const params: Record<string, string> = {};
-    if (parentCategoryId) {
-      params.categoryId = parentCategoryId;
-    }
-    const data = await this.request<SHCategoryListResponse>("category", params);
-    return data.categories;
-  }
-
-  /** Get a single category by ID. */
-  async getCategory(categoryId: string): Promise<SHCategory> {
-    return this.request<SHCategory>(`category/${categoryId}`);
-  }
-
-  // ── Articles ────────────────────────────────────────────────
-
-  /** List all articles in a given category. */
-  async listArticles(categoryId: string): Promise<SHArticle[]> {
-    const data = await this.request<SHArticleListResponse>("article", {
-      categoryId,
-    });
-    return data.articles;
-  }
-
-  /** Get a single article by ID. */
-  async getArticle(articleId: string): Promise<SHArticle> {
-    return this.request<SHArticle>(`article/${articleId}`);
-  }
-
-  // ── Search ──────────────────────────────────────────────────
-
-  /** Full-text search across all articles. Returns paginated results. */
-  async searchArticles(
-    searchText: string,
-    max?: number,
-    offset?: string
-  ): Promise<SHSearchResponse> {
-    const params: Record<string, string> = { searchText };
-    if (max !== undefined) params.max = String(max);
-    if (offset) params.offset = offset;
-    return this.request<SHSearchResponse>("search", params);
-  }
-}

package/src/services/formatting.ts

@@ -1,74 +0,0 @@
-import type { SHCategory, SHArticle } from "../types.js";
-import { CHARACTER_LIMIT } from "../constants.js";
-
-/**
- * Strip HTML tags from article body to produce plain text.
- * Keeps it simple since we just need readable content for the LLM.
- */
-export function stripHtml(html: string): string {
-  return html
-    .replace(/<br\s*\/?>/gi, "\n")
-    .replace(/<\/p>/gi, "\n\n")
-    .replace(/<\/li>/gi, "\n")
-    .replace(/<\/h[1-6]>/gi, "\n\n")
-    .replace(/<[^>]+>/g, "")
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&nbsp;/g, " ")
-    .replace(/\n{3,}/g, "\n\n")
-    .trim();
-}
-
-/** Format a single category for display. */
-export function formatCategory(cat: SHCategory): string {
-  return [
-    `Category: ${cat.name} (ID: ${cat.id})`,
-    `  Level: ${cat.level}`,
-    `  Published articles: ${cat.articlePublishedCount}`,
-    `  Total articles: ${cat.articleCount}`,
-    `  Sub-categories: ${cat.categoriesCount}`,
-    cat.parentId !== "0" ? `  Parent ID: ${cat.parentId}` : null,
-    `  Slug: ${cat.slug}`,
-  ]
-    .filter(Boolean)
-    .join("\n");
-}
-
-/** Format a single article for display. Optionally include body content. */
-export function formatArticle(article: SHArticle, includeBody: boolean = false): string {
-  const lines: string[] = [
-    `Title: ${article.title} (ID: ${article.id})`,
-    `  Category ID: ${article.categoryId}`,
-    `  Type: ${article.type}`,
-    `  Published: ${article.published ? "yes" : "no"}`,
-    `  Created: ${article.dateCreated}`,
-    `  Updated: ${article.lastUpdated}`,
-  ];
-
-  if (article.keywords) {
-    lines.push(`  Keywords: ${article.keywords}`);
-  }
-  if (article.slug) {
-    lines.push(`  Slug: ${article.slug}`);
-  }
-
-  if (includeBody && article.description) {
-    const body = stripHtml(article.description);
-    lines.push("");
-    lines.push("--- Content ---");
-    lines.push(body);
-    lines.push("--- End Content ---");
-  }
-
-  return lines.join("\n");
-}
-
-/** Truncate text if it exceeds the character limit, with a warning. */
-export function truncateIfNeeded(text: string): string {
-  if (text.length <= CHARACTER_LIMIT) return text;
-  const truncated = text.slice(0, CHARACTER_LIMIT);
-  return truncated + "\n\n[Response truncated. Use more specific queries or pagination to get remaining results.]";
-}

package/src/tools/helpCenter.ts

@@ -1,320 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { SupportHeroClient } from "../services/client.js";
-import {
-  formatCategory,
-  formatArticle,
-  truncateIfNeeded,
-} from "../services/formatting.js";
-import {
-  ListCategoriesInputSchema,
-  GetCategoryInputSchema,
-  ListArticlesInputSchema,
-  GetArticleInputSchema,
-  SearchArticlesInputSchema,
-} from "../schemas/inputs.js";
-import type {
-  ListCategoriesInput,
-  GetCategoryInput,
-  ListArticlesInput,
-  GetArticleInput,
-  SearchArticlesInput,
-} from "../schemas/inputs.js";
-
-/**
- * Register all SupportHero tools on the given MCP server.
- */
-export function registerTools(server: McpServer, client: SupportHeroClient): void {
-  // ── List Categories ───────────────────────────────────────
-
-  server.registerTool(
-    "supporthero_list_categories",
-    {
-      title: "List Help Center Categories",
-      description: `List categories in the Propel Help Center.
-
-By default returns all top-level categories. Pass parent_category_id to get
-sub-categories of a specific category.
-
-Use this to discover the category tree before listing articles. Categories
-can be nested up to 3 levels deep.
-
-Args:
-  - parent_category_id (string, optional): ID of parent category to get sub-categories for
-
-Returns:
-  A list of categories with their IDs, names, article counts, and sub-category counts.
-  Use the category ID with supporthero_list_articles to get articles in that category,
-  or with this tool again to drill into sub-categories.`,
-      inputSchema: ListCategoriesInputSchema,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
-    },
-    async (params: ListCategoriesInput) => {
-      try {
-        const categories = await client.listCategories(params.parent_category_id);
-
-        if (categories.length === 0) {
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: params.parent_category_id
-                  ? `No sub-categories found under category ${params.parent_category_id}.`
-                  : "No categories found in the Help Center.",
-              },
-            ],
-          };
-        }
-
-        const text = categories.map(formatCategory).join("\n\n");
-        return {
-          content: [{ type: "text" as const, text: truncateIfNeeded(text) }],
-        };
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Error listing categories: ${error instanceof Error ? error.message : String(error)}`,
-            },
-          ],
-        };
-      }
-    }
-  );
-
-  // ── Get Category ──────────────────────────────────────────
-
-  server.registerTool(
-    "supporthero_get_category",
-    {
-      title: "Get Help Center Category",
-      description: `Get details of a specific Help Center category by ID.
-
-Returns the category name, article counts (total, local, published),
-sub-category count, tree level, and slug.
-
-Args:
-  - category_id (string, required): The category ID
-
-Returns:
-  Full category details including name, article counts, position, and slug.`,
-      inputSchema: GetCategoryInputSchema,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
-    },
-    async (params: GetCategoryInput) => {
-      try {
-        const category = await client.getCategory(params.category_id);
-        return {
-          content: [{ type: "text" as const, text: formatCategory(category) }],
-        };
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Error getting category ${params.category_id}: ${error instanceof Error ? error.message : String(error)}`,
-            },
-          ],
-        };
-      }
-    }
-  );
-
-  // ── List Articles ─────────────────────────────────────────
-
-  server.registerTool(
-    "supporthero_list_articles",
-    {
-      title: "List Articles in Category",
-      description: `List all articles in a specific Help Center category.
-
-Returns article titles, IDs, types, publication status, and dates.
-Does NOT include full article body content (use supporthero_get_article for that).
-
-To find category IDs, use supporthero_list_categories first.
-
-Args:
-  - category_id (string, required): The category ID to list articles from
-
-Returns:
-  A list of article summaries (title, ID, type, published status, dates, keywords).
-  Use the article ID with supporthero_get_article to read the full content.`,
-      inputSchema: ListArticlesInputSchema,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
-    },
-    async (params: ListArticlesInput) => {
-      try {
-        const articles = await client.listArticles(params.category_id);
-
-        if (articles.length === 0) {
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: `No articles found in category ${params.category_id}.`,
-              },
-            ],
-          };
-        }
-
-        const text = articles
-          .map((a) => formatArticle(a, false))
-          .join("\n\n");
-        return {
-          content: [{ type: "text" as const, text: truncateIfNeeded(text) }],
-        };
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Error listing articles for category ${params.category_id}: ${error instanceof Error ? error.message : String(error)}`,
-            },
-          ],
-        };
-      }
-    }
-  );
-
-  // ── Get Article ───────────────────────────────────────────
-
-  server.registerTool(
-    "supporthero_get_article",
-    {
-      title: "Get Help Center Article",
-      description: `Get the full content of a specific Help Center article by ID.
-
-Returns the article title, metadata, and full body content (HTML stripped to plain text).
-Use this to read the actual content of an article found via search or category listing.
-
-Args:
-  - article_id (string, required): The article ID
-
-Returns:
-  Full article including title, category ID, type, publication status, dates,
-  keywords, slug, and the complete article body as plain text.`,
-      inputSchema: GetArticleInputSchema,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
-    },
-    async (params: GetArticleInput) => {
-      try {
-        const article = await client.getArticle(params.article_id);
-        const text = formatArticle(article, true);
-        return {
-          content: [{ type: "text" as const, text: truncateIfNeeded(text) }],
-        };
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Error getting article ${params.article_id}: ${error instanceof Error ? error.message : String(error)}`,
-            },
-          ],
-        };
-      }
-    }
-  );
-
-  // ── Search Articles ───────────────────────────────────────
-
-  server.registerTool(
-    "supporthero_search_articles",
-    {
-      title: "Search Help Center Articles",
-      description: `Full-text search across all Propel Help Center articles.
-
-Searches article titles and body content. Returns paginated results with
-article summaries (no full body). Use supporthero_get_article to read
-the full content of a specific result.
-
-Pagination: The response includes a total count and an offset cursor.
-Pass the offset value from one response into the next request to page
-through results.
-
-Args:
-  - search_text (string, required): The search query
-  - max (number, optional): Results per page, 1 to 100 (default 10)
-  - offset (string, optional): Pagination cursor from previous search response
-
-Returns:
-  A list of matching articles (title, ID, type, published status, dates),
-  total number of matches, and a pagination offset (null if no more results).`,
-      inputSchema: SearchArticlesInputSchema,
-      annotations: {
-        readOnlyHint: true,
-        destructiveHint: false,
-        idempotentHint: true,
-        openWorldHint: true,
-      },
-    },
-    async (params: SearchArticlesInput) => {
-      try {
-        const result = await client.searchArticles(
-          params.search_text,
-          params.max,
-          params.offset
-        );
-
-        if (result.articles.length === 0) {
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: `No articles found matching "${params.search_text}".`,
-              },
-            ],
-          };
-        }
-
-        const header = `Search results for "${params.search_text}": ${result.total} total matches\n`;
-        const articleText = result.articles
-          .map((a) => formatArticle(a, false))
-          .join("\n\n");
-        const footer = result.offset
-          ? `\nMore results available. Pass offset "${result.offset}" to get the next page.`
-          : "\nNo more results.";
-
-        const text = header + "\n" + articleText + footer;
-
-        return {
-          content: [{ type: "text" as const, text: truncateIfNeeded(text) }],
-        };
-      } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Error searching articles: ${error instanceof Error ? error.message : String(error)}`,
-            },
-          ],
-        };
-      }
-    }
-  );
-}

package/src/types.ts

@@ -1,50 +0,0 @@
-// SupportHero API response types
-
-export interface SHCategory {
-  id: string;
-  articleCount: number;
-  articleLocalCount: number;
-  articlePublishedCount: number;
-  categoriesCount: number;
-  level: number;
-  parentId: string;
-  name: string;
-  position: number;
-  slug: string;
-}
-
-export interface SHCategoryListResponse {
-  categories: SHCategory[];
-}
-
-export interface SHArticle {
-  id: string;
-  categoryId: string;
-  countryCode: string;
-  dateCreated: string;
-  description: string; // HTML body content
-  keywords: string;
-  language: string;
-  lastUpdated: string;
-  metaCanonical: string;
-  metaDescription: string;
-  metaKeywords: string;
-  metaTitle: string;
-  position: number;
-  published: boolean;
-  slug: string;
-  title: string;
-  type: "article" | "tutorial";
-  videoThumbnailUrl: string;
-  videoUrl: string;
-}
-
-export interface SHArticleListResponse {
-  articles: SHArticle[];
-}
-
-export interface SHSearchResponse {
-  articles: SHArticle[];
-  total: number;
-  offset: string | null;
-}

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}