@cyanheads/stackexchange-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/index.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Barrel export for all Stack Exchange MCP tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { stackexchangeGetTagFaq } from './stackexchange-get-tag-faq.tool.js';
+export { stackexchangeGetThread } from './stackexchange-get-thread.tool.js';
+export { stackexchangeGetUser } from './stackexchange-get-user.tool.js';
+export { stackexchangeListSites } from './stackexchange-list-sites.tool.js';
+export { stackexchangeSearchQuestions } from './stackexchange-search-questions.tool.js';
+export declare const allToolDefinitions: (import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    tag: import("zod").ZodString;
+    site: import("zod").ZodDefault<import("zod").ZodString>;
+    pageSize: import("zod").ZodDefault<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    questions: import("zod").ZodArray<import("zod").ZodObject<{
+        questionId: import("zod").ZodNumber;
+        title: import("zod").ZodString;
+        link: import("zod").ZodString;
+        score: import("zod").ZodNumber;
+        answerCount: import("zod").ZodNumber;
+        isAnswered: import("zod").ZodBoolean;
+        tags: import("zod").ZodArray<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    tag: import("zod").ZodString;
+    site: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "invalid_site";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "The provided site value is not a valid Stack Exchange network site identifier.";
+    readonly recovery: "Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.";
+}, {
+    readonly reason: "quota_exceeded";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: "The Stack Exchange API quota_remaining has reached 0.";
+    readonly recovery: "Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.";
+}], {
+    readonly quotaRemaining: import("zod").ZodNumber;
+    readonly quotaMax: import("zod").ZodNumber;
+}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    questionIdOrUrl: import("zod").ZodString;
+    site: import("zod").ZodDefault<import("zod").ZodString>;
+    maxAnswers: import("zod").ZodDefault<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    questionId: import("zod").ZodNumber;
+    title: import("zod").ZodString;
+    link: import("zod").ZodString;
+    score: import("zod").ZodNumber;
+    tags: import("zod").ZodArray<import("zod").ZodString>;
+    bodyMarkdown: import("zod").ZodString;
+    authorName: import("zod").ZodOptional<import("zod").ZodString>;
+    authorLink: import("zod").ZodOptional<import("zod").ZodString>;
+    acceptedAnswerId: import("zod").ZodOptional<import("zod").ZodNumber>;
+    answers: import("zod").ZodArray<import("zod").ZodObject<{
+        answerId: import("zod").ZodNumber;
+        score: import("zod").ZodNumber;
+        isAccepted: import("zod").ZodBoolean;
+        bodyMarkdown: import("zod").ZodString;
+        authorName: import("zod").ZodOptional<import("zod").ZodString>;
+        authorLink: import("zod").ZodOptional<import("zod").ZodString>;
+        authorReputation: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "question_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "The question lookup returns an empty result set — SE returns HTTP 200 with no items for unknown question IDs rather than 404.";
+    readonly recovery: "Verify the question ID or run stackexchange_search_questions to find a valid question ID.";
+}, {
+    readonly reason: "invalid_site";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "The provided site value is not a valid Stack Exchange network site identifier.";
+    readonly recovery: "Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.";
+}, {
+    readonly reason: "invalid_id_or_url";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "The input is not a parseable integer ID and not a recognizable SE question URL.";
+    readonly recovery: "Provide a numeric question ID (e.g. \"11227809\") or a valid Stack Exchange question URL.";
+}, {
+    readonly reason: "quota_exceeded";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: "The Stack Exchange API quota_remaining has reached 0.";
+    readonly recovery: "Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.";
+}], {
+    readonly quotaRemaining: import("zod").ZodNumber;
+    readonly quotaMax: import("zod").ZodNumber;
+}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    userId: import("zod").ZodNumber;
+    site: import("zod").ZodDefault<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    userId: import("zod").ZodNumber;
+    displayName: import("zod").ZodString;
+    link: import("zod").ZodString;
+    reputation: import("zod").ZodNumber;
+    badgeCounts: import("zod").ZodOptional<import("zod").ZodObject<{
+        gold: import("zod").ZodOptional<import("zod").ZodNumber>;
+        silver: import("zod").ZodOptional<import("zod").ZodNumber>;
+        bronze: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>>;
+    location: import("zod").ZodOptional<import("zod").ZodString>;
+    websiteUrl: import("zod").ZodOptional<import("zod").ZodString>;
+    answerCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+    questionCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+    topTags: import("zod").ZodArray<import("zod").ZodObject<{
+        tagName: import("zod").ZodString;
+        answerCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+        answerScore: import("zod").ZodOptional<import("zod").ZodNumber>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "user_not_found";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.NotFound;
+    readonly when: "The user lookup returns an empty result set — SE returns HTTP 200 with no items for unknown user IDs rather than 404.";
+    readonly recovery: "Verify the user ID or look up a valid ID from an answer via stackexchange_get_thread.";
+}, {
+    readonly reason: "invalid_site";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "The provided site value is not a valid Stack Exchange network site identifier.";
+    readonly recovery: "Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.";
+}, {
+    readonly reason: "quota_exceeded";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: "The Stack Exchange API quota_remaining has reached 0.";
+    readonly recovery: "Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.";
+}], {
+    readonly quotaRemaining: import("zod").ZodNumber;
+    readonly quotaMax: import("zod").ZodNumber;
+}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    filter: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    sites: import("zod").ZodArray<import("zod").ZodObject<{
+        name: import("zod").ZodString;
+        apiSiteParameter: import("zod").ZodString;
+        siteUrl: import("zod").ZodString;
+        audience: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+    totalCount: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>, undefined, {
+    readonly quotaRemaining: import("zod").ZodNumber;
+    readonly quotaMax: import("zod").ZodNumber;
+}> | import("@cyanheads/mcp-ts-core").ToolDefinition<import("zod").ZodObject<{
+    query: import("zod").ZodString;
+    site: import("zod").ZodDefault<import("zod").ZodString>;
+    tags: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+    acceptedOnly: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    minScore: import("zod").ZodOptional<import("zod").ZodNumber>;
+    sort: import("zod").ZodDefault<import("zod").ZodEnum<{
+        relevance: "relevance";
+        votes: "votes";
+        activity: "activity";
+        newest: "newest";
+    }>>;
+    pageSize: import("zod").ZodDefault<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    questions: import("zod").ZodArray<import("zod").ZodObject<{
+        questionId: import("zod").ZodNumber;
+        title: import("zod").ZodString;
+        link: import("zod").ZodString;
+        score: import("zod").ZodNumber;
+        answerCount: import("zod").ZodNumber;
+        isAnswered: import("zod").ZodBoolean;
+        tags: import("zod").ZodArray<import("zod").ZodString>;
+        excerpt: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, readonly [{
+    readonly reason: "invalid_site";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.InvalidParams;
+    readonly when: "The provided site value is not a valid Stack Exchange network site identifier.";
+    readonly recovery: "Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.";
+}, {
+    readonly reason: "quota_exceeded";
+    readonly code: import("@cyanheads/mcp-ts-core/errors").JsonRpcErrorCode.RateLimited;
+    readonly when: "The Stack Exchange API quota_remaining has reached 0.";
+    readonly recovery: "Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.";
+}], {
+    readonly quotaRemaining: import("zod").ZodNumber;
+    readonly quotaMax: import("zod").ZodNumber;
+}>)[];
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp-server/tools/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AAQxF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAM9B,CAAC"}

package/dist/mcp-server/tools/definitions/index.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Barrel export for all Stack Exchange MCP tool definitions.
+ * @module mcp-server/tools/definitions/index
+ */
+export { stackexchangeGetTagFaq } from './stackexchange-get-tag-faq.tool.js';
+export { stackexchangeGetThread } from './stackexchange-get-thread.tool.js';
+export { stackexchangeGetUser } from './stackexchange-get-user.tool.js';
+export { stackexchangeListSites } from './stackexchange-list-sites.tool.js';
+export { stackexchangeSearchQuestions } from './stackexchange-search-questions.tool.js';
+import { stackexchangeGetTagFaq } from './stackexchange-get-tag-faq.tool.js';
+import { stackexchangeGetThread } from './stackexchange-get-thread.tool.js';
+import { stackexchangeGetUser } from './stackexchange-get-user.tool.js';
+import { stackexchangeListSites } from './stackexchange-list-sites.tool.js';
+import { stackexchangeSearchQuestions } from './stackexchange-search-questions.tool.js';
+export const allToolDefinitions = [
+    stackexchangeListSites,
+    stackexchangeSearchQuestions,
+    stackexchangeGetTagFaq,
+    stackexchangeGetUser,
+    stackexchangeGetThread,
+];
+//# sourceMappingURL=index.js.map

package/dist/mcp-server/tools/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AAExF,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,4BAA4B,EAAE,MAAM,0CAA0C,CAAC;AAExF,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,sBAAsB;IACtB,4BAA4B;IAC5B,sBAAsB;IACtB,oBAAoB;IACpB,sBAAsB;CACvB,CAAC"}

package/dist/mcp-server/tools/definitions/stackexchange-get-tag-faq.tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Tool to fetch the highest-voted answered questions for a tag (tag FAQ).
+ * @module mcp-server/tools/definitions/stackexchange-get-tag-faq
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const stackexchangeGetTagFaq: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    tag: z.ZodString;
+    site: z.ZodDefault<z.ZodString>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    questions: z.ZodArray<z.ZodObject<{
+        questionId: z.ZodNumber;
+        title: z.ZodString;
+        link: z.ZodString;
+        score: z.ZodNumber;
+        answerCount: z.ZodNumber;
+        isAnswered: z.ZodBoolean;
+        tags: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    tag: z.ZodString;
+    site: z.ZodString;
+}, z.core.$strip>, readonly [{
+    readonly reason: "invalid_site";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "The provided site value is not a valid Stack Exchange network site identifier.";
+    readonly recovery: "Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.";
+}, {
+    readonly reason: "quota_exceeded";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "The Stack Exchange API quota_remaining has reached 0.";
+    readonly recovery: "Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.";
+}], {
+    readonly quotaRemaining: z.ZodNumber;
+    readonly quotaMax: z.ZodNumber;
+}>;
+//# sourceMappingURL=stackexchange-get-tag-faq.tool.d.ts.map

package/dist/mcp-server/tools/definitions/stackexchange-get-tag-faq.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackexchange-get-tag-faq.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/stackexchange-get-tag-faq.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoIjC,CAAC"}

package/dist/mcp-server/tools/definitions/stackexchange-get-tag-faq.tool.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Tool to fetch the highest-voted answered questions for a tag (tag FAQ).
+ * @module mcp-server/tools/definitions/stackexchange-get-tag-faq
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getStackExchangeService } from '../../../services/stackexchange/stackexchange-service.js';
+export const stackexchangeGetTagFaq = tool('stackexchange_get_tag_faq', {
+    title: 'Get Stack Exchange Tag FAQ',
+    description: 'Fetch the highest-voted answered questions for a tag on a Stack Exchange site — the canonical "best answers in X" list. ' +
+        'Returns a question list without bodies; use stackexchange_get_thread to read the full body and answers for any result. ' +
+        'Use this tool to find the authoritative community resources on a topic (e.g. tag "javascript" on stackoverflow). ' +
+        'Use stackexchange_search_questions for free-text search rather than tag-based browsing.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    input: z.object({
+        tag: z
+            .string()
+            .describe('Tag to look up (e.g. "python", "javascript", "docker"). Must match exactly.'),
+        site: z
+            .string()
+            .default('stackoverflow')
+            .describe('Stack Exchange site — use the api_site_parameter value (e.g. "stackoverflow", "superuser"). ' +
+            'Defaults to "stackoverflow". Call stackexchange_list_sites to discover valid values.'),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(30)
+            .default(10)
+            .describe('Number of results to return (1–30, default 10).'),
+    }),
+    output: z.object({
+        questions: z
+            .array(z
+            .object({
+            questionId: z
+                .number()
+                .int()
+                .describe('Question ID — pass to stackexchange_get_thread to fetch the full thread.'),
+            title: z.string().describe('Question title.'),
+            link: z.string().describe('Direct URL to the question.'),
+            score: z.number().int().describe('Question score (upvotes minus downvotes).'),
+            answerCount: z.number().int().describe('Total number of answers.'),
+            isAnswered: z
+                .boolean()
+                .describe('True when the question has an accepted answer or at least one positively-scored answer.'),
+            tags: z
+                .array(z.string().describe('A tag applied to this question.'))
+                .describe('Tags applied to this question.'),
+        })
+            .describe('A Stack Exchange FAQ question with score, answer count, and tags.'))
+            .describe('Highest-voted answered questions for the specified tag, ordered by votes.'),
+        tag: z.string().describe('Tag name used for this FAQ lookup.'),
+        site: z.string().describe('Stack Exchange site api_site_parameter used for this lookup.'),
+    }),
+    enrichment: {
+        quotaRemaining: z.number().describe('Remaining API quota calls for the current day.'),
+        quotaMax: z
+            .number()
+            .describe('Maximum API quota calls per day (300 keyless, ~10,000 with API key).'),
+    },
+    enrichmentTrailer: {
+        quotaRemaining: { label: 'Quota Remaining' },
+        quotaMax: { label: 'Quota Max' },
+    },
+    errors: [
+        {
+            reason: 'invalid_site',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'The provided site value is not a valid Stack Exchange network site identifier.',
+            recovery: 'Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.',
+        },
+        {
+            reason: 'quota_exceeded',
+            code: JsonRpcErrorCode.RateLimited,
+            when: 'The Stack Exchange API quota_remaining has reached 0.',
+            recovery: 'Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getStackExchangeService();
+        const { questions, quotaRemaining, quotaMax } = await svc.getTagFaq({
+            tag: input.tag,
+            site: input.site,
+            pageSize: input.pageSize,
+        }, ctx);
+        ctx.enrich({ quotaRemaining, quotaMax });
+        if (questions.length === 0) {
+            ctx.enrich.notice(`No FAQ questions found for tag "${input.tag}" on ${input.site}. Verify the tag name or try a different site.`);
+        }
+        ctx.log.info('Fetched SE tag FAQ', {
+            tag: input.tag,
+            site: input.site,
+            count: questions.length,
+        });
+        return { questions, tag: input.tag, site: input.site };
+    },
+    format: (result) => {
+        const lines = [`## Tag FAQ: \`${result.tag}\` on ${result.site}\n`];
+        if (result.questions.length === 0) {
+            lines.push('No FAQ questions found for this tag.');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        for (const q of result.questions) {
+            lines.push(`### ${q.title}`);
+            lines.push(`**ID:** ${q.questionId} | **Score:** ${q.score} | **Answers:** ${q.answerCount} | **Answered:** ${q.isAnswered ? 'Yes' : 'No'}`);
+            lines.push(`**Tags:** ${q.tags.join(', ')}`);
+            lines.push(`**Link:** ${q.link}`);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=stackexchange-get-tag-faq.tool.js.map

package/dist/mcp-server/tools/definitions/stackexchange-get-tag-faq.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackexchange-get-tag-faq.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/stackexchange-get-tag-faq.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/stackexchange-get-thread.tool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Tool to fetch a complete Stack Exchange Q&A thread with HTML→markdown normalization.
+ * @module mcp-server/tools/definitions/stackexchange-get-thread
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const stackexchangeGetThread: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    questionIdOrUrl: z.ZodString;
+    site: z.ZodDefault<z.ZodString>;
+    maxAnswers: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    questionId: z.ZodNumber;
+    title: z.ZodString;
+    link: z.ZodString;
+    score: z.ZodNumber;
+    tags: z.ZodArray<z.ZodString>;
+    bodyMarkdown: z.ZodString;
+    authorName: z.ZodOptional<z.ZodString>;
+    authorLink: z.ZodOptional<z.ZodString>;
+    acceptedAnswerId: z.ZodOptional<z.ZodNumber>;
+    answers: z.ZodArray<z.ZodObject<{
+        answerId: z.ZodNumber;
+        score: z.ZodNumber;
+        isAccepted: z.ZodBoolean;
+        bodyMarkdown: z.ZodString;
+        authorName: z.ZodOptional<z.ZodString>;
+        authorLink: z.ZodOptional<z.ZodString>;
+        authorReputation: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "question_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The question lookup returns an empty result set — SE returns HTTP 200 with no items for unknown question IDs rather than 404.";
+    readonly recovery: "Verify the question ID or run stackexchange_search_questions to find a valid question ID.";
+}, {
+    readonly reason: "invalid_site";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "The provided site value is not a valid Stack Exchange network site identifier.";
+    readonly recovery: "Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.";
+}, {
+    readonly reason: "invalid_id_or_url";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "The input is not a parseable integer ID and not a recognizable SE question URL.";
+    readonly recovery: "Provide a numeric question ID (e.g. \"11227809\") or a valid Stack Exchange question URL.";
+}, {
+    readonly reason: "quota_exceeded";
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: "The Stack Exchange API quota_remaining has reached 0.";
+    readonly recovery: "Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.";
+}], {
+    readonly quotaRemaining: z.ZodNumber;
+    readonly quotaMax: z.ZodNumber;
+}>;
+//# sourceMappingURL=stackexchange-get-thread.tool.d.ts.map

package/dist/mcp-server/tools/definitions/stackexchange-get-thread.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackexchange-get-thread.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/stackexchange-get-thread.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA0BjE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmNjC,CAAC"}

package/dist/mcp-server/tools/definitions/stackexchange-get-thread.tool.js

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Tool to fetch a complete Stack Exchange Q&A thread with HTML→markdown normalization.
+ * @module mcp-server/tools/definitions/stackexchange-get-thread
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getStackExchangeService } from '../../../services/stackexchange/stackexchange-service.js';
+/**
+ * Parse a question ID from either a numeric string or a Stack Exchange question URL.
+ * Returns null if the input cannot be parsed as a valid SE question ID.
+ */
+function parseQuestionIdOrUrl(input) {
+    const trimmed = input.trim();
+    // Numeric ID directly
+    if (/^\d+$/.test(trimmed)) {
+        return parseInt(trimmed, 10);
+    }
+    // Full SE question URL: extract the integer immediately after /questions/
+    // Handles: https://stackoverflow.com/questions/11227809/...
+    //          https://stackoverflow.com/questions/11227809/title#answerAnchor
+    const match = trimmed.match(/\/questions\/(\d+)/);
+    if (match?.[1]) {
+        return parseInt(match[1], 10);
+    }
+    return null;
+}
+export const stackexchangeGetThread = tool('stackexchange_get_thread', {
+    title: 'Get Stack Exchange Q&A Thread',
+    description: 'Fetch a complete Q&A thread — question body and all answers, accepted answer first then sorted by score, ' +
+        'rendered as clean markdown with fenced code blocks. Accepts an integer question ID or a full Stack Exchange ' +
+        'question URL (e.g. "https://stackoverflow.com/questions/11227809/why-is-processing-a-sorted-array-faster" or ' +
+        '"11227809"). HTML is normalized to markdown automatically; attribution (author + link) included per CC BY-SA 4.0. ' +
+        'Get question IDs from stackexchange_search_questions or stackexchange_get_tag_faq.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    input: z.object({
+        questionIdOrUrl: z
+            .string()
+            .describe('Numeric question ID (e.g. "11227809") or a full Stack Exchange question URL ' +
+            '(e.g. "https://stackoverflow.com/questions/11227809/why-is-processing-a-sorted-array-faster"). ' +
+            'The integer immediately following /questions/ is extracted from URLs.'),
+        site: z
+            .string()
+            .default('stackoverflow')
+            .describe('Stack Exchange site — use the api_site_parameter value (e.g. "stackoverflow", "superuser"). ' +
+            'Defaults to "stackoverflow". Must match the site where the question lives. ' +
+            'Call stackexchange_list_sites to discover valid values.'),
+        maxAnswers: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(10)
+            .describe('Maximum number of answers to include (1–100, default 10). Answers are sorted: accepted first, then by score.'),
+    }),
+    output: z.object({
+        questionId: z
+            .number()
+            .int()
+            .describe('Numeric question ID — identifies this thread on the site.'),
+        title: z.string().describe('Question title.'),
+        link: z.string().describe('Direct URL to the question.'),
+        score: z.number().int().describe('Question score (upvotes minus downvotes).'),
+        tags: z
+            .array(z.string().describe('A tag applied to this question.'))
+            .describe('Tags applied to this question.'),
+        bodyMarkdown: z.string().describe('Question body normalized from HTML to markdown.'),
+        authorName: z.string().optional().describe('Question author display name when available.'),
+        authorLink: z.string().optional().describe('Question author profile URL when available.'),
+        acceptedAnswerId: z
+            .number()
+            .int()
+            .optional()
+            .describe('ID of the accepted answer when one exists.'),
+        answers: z
+            .array(z
+            .object({
+            answerId: z.number().int().describe('Numeric answer ID.'),
+            score: z.number().int().describe('Answer score (upvotes minus downvotes).'),
+            isAccepted: z.boolean().describe('True when this is the accepted answer.'),
+            bodyMarkdown: z.string().describe('Answer body normalized from HTML to markdown.'),
+            authorName: z
+                .string()
+                .optional()
+                .describe('Answer author display name when available.'),
+            authorLink: z.string().optional().describe('Answer author profile URL when available.'),
+            authorReputation: z
+                .number()
+                .int()
+                .optional()
+                .describe('Answer author reputation when available.'),
+        })
+            .describe('A single Q&A answer with markdown body, score, and author attribution.'))
+            .describe('Answers sorted: accepted answer first, then by score descending.'),
+    }),
+    enrichment: {
+        quotaRemaining: z.number().describe('Remaining API quota calls for the current day.'),
+        quotaMax: z
+            .number()
+            .describe('Maximum API quota calls per day (300 keyless, ~10,000 with API key).'),
+    },
+    enrichmentTrailer: {
+        quotaRemaining: { label: 'Quota Remaining' },
+        quotaMax: { label: 'Quota Max' },
+    },
+    errors: [
+        {
+            reason: 'question_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The question lookup returns an empty result set — SE returns HTTP 200 with no items for unknown question IDs rather than 404.',
+            recovery: 'Verify the question ID or run stackexchange_search_questions to find a valid question ID.',
+        },
+        {
+            reason: 'invalid_site',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'The provided site value is not a valid Stack Exchange network site identifier.',
+            recovery: 'Call stackexchange_list_sites to discover valid site api_site_parameter values and retry.',
+        },
+        {
+            reason: 'invalid_id_or_url',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'The input is not a parseable integer ID and not a recognizable SE question URL.',
+            recovery: 'Provide a numeric question ID (e.g. "11227809") or a valid Stack Exchange question URL.',
+        },
+        {
+            reason: 'quota_exceeded',
+            code: JsonRpcErrorCode.RateLimited,
+            when: 'The Stack Exchange API quota_remaining has reached 0.',
+            recovery: 'Quota resets at midnight UTC; set STACKEXCHANGE_API_KEY to lift the limit to 10,000 per day.',
+        },
+    ],
+    async handler(input, ctx) {
+        const questionId = parseQuestionIdOrUrl(input.questionIdOrUrl);
+        if (questionId === null) {
+            throw ctx.fail('invalid_id_or_url', `Cannot parse "${input.questionIdOrUrl}" as a question ID or SE question URL.`, { ...ctx.recoveryFor('invalid_id_or_url'), input: input.questionIdOrUrl });
+        }
+        const svc = getStackExchangeService();
+        const { thread, quotaRemaining, quotaMax } = await svc.getThread({
+            questionId,
+            site: input.site,
+            maxAnswers: input.maxAnswers,
+        }, ctx);
+        ctx.enrich({ quotaRemaining, quotaMax });
+        ctx.log.info('Fetched SE thread', {
+            questionId,
+            site: input.site,
+            answerCount: thread.answers.length,
+        });
+        return thread;
+    },
+    format: (result) => {
+        const lines = [];
+        // Question header
+        lines.push(`# ${result.title}`);
+        lines.push(`**Question ID:** ${result.questionId} | **Score:** ${result.score}`);
+        lines.push(`**Tags:** ${result.tags.join(', ')}`);
+        lines.push(`**Link:** ${result.link}`);
+        if (result.authorName) {
+            const authorRef = result.authorLink
+                ? `[${result.authorName}](${result.authorLink})`
+                : result.authorName;
+            lines.push(`**Author:** ${authorRef}`);
+        }
+        if (result.acceptedAnswerId != null) {
+            lines.push(`**Accepted Answer ID:** ${result.acceptedAnswerId}`);
+        }
+        lines.push('');
+        // Question body
+        lines.push('## Question');
+        lines.push('');
+        lines.push(result.bodyMarkdown);
+        lines.push('');
+        // Answers
+        if (result.answers.length === 0) {
+            lines.push('*No answers yet.*');
+        }
+        else {
+            lines.push(`---\n\n## Answers (${result.answers.length})`);
+            for (const a of result.answers) {
+                lines.push('');
+                const acceptedBadge = a.isAccepted ? ' ✓ Accepted' : '';
+                lines.push(`### Answer ${a.answerId}${acceptedBadge}`);
+                // Attribution per CC BY-SA 4.0
+                const attrParts = [`**Score:** ${a.score}`];
+                if (a.authorName) {
+                    const authorRef = a.authorLink ? `[${a.authorName}](${a.authorLink})` : a.authorName;
+                    attrParts.push(`**Author:** ${authorRef}`);
+                    if (a.authorReputation != null) {
+                        attrParts.push(`rep: ${a.authorReputation.toLocaleString()}`);
+                    }
+                }
+                lines.push(attrParts.join(' | '));
+                lines.push('');
+                lines.push(a.bodyMarkdown);
+                lines.push('');
+            }
+        }
+        lines.push(`---\n*Content licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)*`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=stackexchange-get-thread.tool.js.map