@cyanheads/stackexchange-mcp-server 0.1.1

package/dist/services/stackexchange/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Stack Exchange API v2.3 response types for raw upstream payloads.
+ * All optional fields reflect real upstream sparsity — fields may be absent entirely.
+ * @module services/stackexchange/types
+ */
+/** Wrapper around every SE API response. */
+export interface SeWrapper<T> {
+    /** Seconds to wait before the next request — honor when present. */
+    backoff?: number;
+    has_more: boolean;
+    items: T[];
+    quota_max: number;
+    quota_remaining: number;
+}
+/** SE API error response (HTTP 400/500). */
+export interface SeError {
+    error_id: number;
+    error_message: string;
+    error_name: string;
+}
+/** A Stack Exchange question (raw upstream). */
+export interface SeQuestion {
+    accepted_answer_id?: number;
+    answer_count: number;
+    /** Present only when filter=withbody is used. */
+    body?: string;
+    creation_date?: number;
+    /** Excerpt from search results (search endpoint only). */
+    excerpt?: string;
+    is_answered: boolean;
+    last_activity_date?: number;
+    link: string;
+    owner?: SeShallowUser;
+    question_id: number;
+    score: number;
+    tags: string[];
+    title: string;
+    view_count?: number;
+}
+/** A Stack Exchange answer (raw upstream). */
+export interface SeAnswer {
+    answer_id: number;
+    /** Present only when filter=withbody is used. */
+    body?: string;
+    creation_date?: number;
+    is_accepted: boolean;
+    last_activity_date?: number;
+    owner?: SeShallowUser;
+    question_id: number;
+    score: number;
+}
+/** Shallow user object embedded in questions/answers. */
+export interface SeShallowUser {
+    display_name?: string;
+    link?: string;
+    reputation?: number;
+    user_id?: number;
+    user_type?: string;
+}
+/** Full user profile (raw upstream). */
+export interface SeUser {
+    about_me?: string;
+    accept_rate?: number;
+    answer_count?: number;
+    badge_counts?: {
+        bronze?: number;
+        silver?: number;
+        gold?: number;
+    };
+    creation_date?: number;
+    display_name: string;
+    last_access_date?: number;
+    link: string;
+    location?: string;
+    profile_image?: string;
+    question_count?: number;
+    reputation: number;
+    user_id: number;
+    user_type?: string;
+    view_count?: number;
+    website_url?: string;
+}
+/** Top tag entry for a user (raw upstream). */
+export interface SeTopTag {
+    answer_count?: number;
+    answer_score?: number;
+    question_count?: number;
+    question_score?: number;
+    tag_name: string;
+}
+/** Site entry from /sites endpoint (raw upstream). */
+export interface SeSite {
+    /** The value to pass as the `site` parameter on all other endpoints. */
+    api_site_parameter: string;
+    audience?: string;
+    /** Raw icon or logo image URL. */
+    icon_url?: string;
+    launch_date?: number;
+    name: string;
+    site_state?: string;
+    site_type?: string;
+    site_url: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/stackexchange/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/stackexchange/types.ts"],"names":[],"mappings":"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"}

package/dist/services/stackexchange/types.js

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Stack Exchange API v2.3 response types for raw upstream payloads.
+ * All optional fields reflect real upstream sparsity — fields may be absent entirely.
+ * @module services/stackexchange/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/stackexchange/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/stackexchange/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@cyanheads/stackexchange-mcp-server",
+  "version": "0.1.1",
+  "mcpName": "io.github.cyanheads/stackexchange-mcp-server",
+  "description": "Search Stack Exchange questions, fetch complete Q&A threads as clean markdown, browse tag FAQs, and look up user profiles via MCP. STDIO or Streamable HTTP.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "stackexchange-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "changelog/",
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "Dockerfile",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "rebuild": "bun run scripts/clean.ts && bun run scripts/build.ts",
+    "clean": "bun run scripts/clean.ts",
+    "devcheck": "bun run scripts/devcheck.ts",
+    "audit:refresh": "rm -f bun.lock && bun install && bun audit",
+    "tree": "bun run scripts/tree.ts",
+    "list-skills": "bun run scripts/list-skills.ts",
+    "format": "biome check --write .",
+    "format:unsafe": "biome check --write --unsafe .",
+    "lint:mcp": "bun run scripts/lint-mcp.ts",
+    "lint:packaging": "bun run scripts/lint-packaging.ts",
+    "bundle": "npm run build && npx -y @anthropic-ai/mcpb pack . dist/stackexchange-mcp-server.mcpb",
+    "changelog:build": "bun run scripts/build-changelog.ts",
+    "changelog:check": "bun run scripts/build-changelog.ts --check",
+    "release:github": "bun run scripts/release-github.ts",
+    "publish-mcp": "mcp-publisher login github -token \"$(security find-generic-password -a \"$USER\" -s mcp-publisher-github-pat -w)\" && mcp-publisher publish",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+  },
+  "keywords": [
+    "stackexchange",
+    "stack-overflow",
+    "stack-exchange",
+    "qa",
+    "questions-answers",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "typescript",
+    "bun",
+    "stdio",
+    "streamable-http",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/stackexchange-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cyanheads/stackexchange-mcp-server/issues"
+  },
+  "homepage": "https://github.com/cyanheads/stackexchange-mcp-server#readme",
+  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/stackexchange-mcp-server#readme)",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/cyanheads"
+    },
+    {
+      "type": "buy_me_a_coffee",
+      "url": "https://www.buymeacoffee.com/cyanheads"
+    }
+  ],
+  "license": "Apache-2.0",
+  "packageManager": "bun@1.3.11",
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.9.21",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@types/node": "^25.9.1",
+    "depcheck": "^1.4.7",
+    "ignore": "^7.0.5",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/server.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.cyanheads/stackexchange-mcp-server",
+  "description": "Search Stack Exchange questions, fetch Q&A threads as markdown, look up tag FAQs and user profiles.",
+  "repository": {
+    "url": "https://github.com/cyanheads/stackexchange-mcp-server",
+    "source": "github"
+  },
+  "version": "0.1.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/stackexchange-mcp-server",
+      "runtimeHint": "bun",
+      "version": "0.1.1",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "run"
+        },
+        {
+          "type": "positional",
+          "value": "start:stdio"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "STACKEXCHANGE_API_KEY",
+          "description": "Stack Exchange API key — lifts per-IP quota from ~300/day to ~10,000/day. Register at https://stackapps.com/apps/oauth/register.",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/stackexchange-mcp-server",
+      "runtimeHint": "bun",
+      "version": "0.1.1",
+      "packageArguments": [
+        {
+          "type": "positional",
+          "value": "run"
+        },
+        {
+          "type": "positional",
+          "value": "start:http"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "STACKEXCHANGE_API_KEY",
+          "description": "Stack Exchange API key — lifts per-IP quota from ~300/day to ~10,000/day. Register at https://stackapps.com/apps/oauth/register.",
+          "format": "string",
+          "isRequired": false
+        },
+        {
+          "name": "MCP_HTTP_HOST",
+          "description": "The hostname for the HTTP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "127.0.0.1"
+        },
+        {
+          "name": "MCP_HTTP_PORT",
+          "description": "The port to run the HTTP server on.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3010"
+        },
+        {
+          "name": "MCP_HTTP_ENDPOINT_PATH",
+          "description": "The endpoint path for the MCP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "/mcp"
+        },
+        {
+          "name": "MCP_AUTH_MODE",
+          "description": "Authentication mode to use: 'none', 'jwt', or 'oauth'.",
+          "format": "string",
+          "isRequired": false,
+          "default": "none"
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        }
+      ],
+      "transport": {
+        "type": "streamable-http",
+        "url": "http://localhost:3010/mcp"
+      }
+    }
+  ]
+}