gangtise-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gangtiser
+
+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/README.md

@@ -0,0 +1,102 @@
+# gangtise-mcp
+
+基于 [Gangtise OpenAPI](https://open.gangtise.com) 的 MCP（Model Context Protocol）服务，让 Claude 等 AI 助手直接访问 Gangtise 投研平台数据。
+
+## 功能覆盖
+
+| 类别 | 工具 |
+|---|---|
+| 参考数据 | `gangtise_lookup` — 研究方向、券商、行业、地区、公告类别、申万行业代码、主题 ID |
+| 证券检索 | `gangtise_securities_search` |
+| 观点/研报 | 国内首席观点、纪要、券商研报、外资研报、外资独立观点、公告（A股/港股） |
+| 路演/调研 | 路演、调研、策略会、论坛 |
+| 行情 | A 股/港股日 K、A 股分钟 K、指数日 K |
+| 基本面 | 利润表、资产负债表、现金流量表（累计/单季）、主营业务、估值、股东、盈利预测 |
+| AI 能力 | 知识库检索、一页通、投资逻辑、同业对比、线索、主题跟踪、业绩点评、观点辩证 |
+| 云盘/语音 | 网盘文件、录音转写、我的会议、微信群消息 |
+
+## 前置要求
+
+- Node.js ≥ 20
+- Gangtise 开放平台账号（[申请地址](https://open.gangtise.com)），获取 `accessKey` / `secretKey`
+
+## 快速开始
+
+### 方式一：npx（推荐，无需安装）
+
+在 Claude Code 或 Claude Desktop 配置文件中直接使用：
+
+```json
+{
+  "mcpServers": {
+    "gangtise": {
+      "command": "npx",
+      "args": ["-y", "gangtise-mcp"],
+      "env": {
+        "GANGTISE_ACCESS_KEY": "your_access_key",
+        "GANGTISE_SECRET_KEY": "your_secret_key"
+      }
+    }
+  }
+}
+```
+
+### 方式二：克隆仓库本地运行
+
+```bash
+git clone https://github.com/gangtiser/gangtise-mcp
+cd gangtise-mcp
+npm install
+npm run build
+```
+
+配置文件：
+
+```json
+{
+  "mcpServers": {
+    "gangtise": {
+      "command": "node",
+      "args": ["/path/to/gangtise-mcp/dist/index.js"],
+      "env": {
+        "GANGTISE_ACCESS_KEY": "your_access_key",
+        "GANGTISE_SECRET_KEY": "your_secret_key"
+      }
+    }
+  }
+}
+```
+
+### Claude Code 一键添加
+
+```bash
+claude mcp add gangtise -e GANGTISE_ACCESS_KEY=your_key -e GANGTISE_SECRET_KEY=your_secret -- npx -y gangtise-mcp
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `GANGTISE_ACCESS_KEY` | — | 开放平台 Access Key（与 SECRET_KEY 配对使用） |
+| `GANGTISE_SECRET_KEY` | — | 开放平台 Secret Key |
+| `GANGTISE_TOKEN` | — | 直接传 Bearer Token（优先于 Key/Secret，适合临时使用） |
+| `GANGTISE_BASE_URL` | `https://open.gangtise.com` | API 基础地址 |
+| `GANGTISE_TIMEOUT_MS` | `30000` | 单次请求超时（毫秒） |
+| `GANGTISE_MCP_ASYNC_TIMEOUT_MS` | `180000` | 异步 AI 任务等待超时（毫秒） |
+| `GANGTISE_TOKEN_CACHE_PATH` | `~/.config/gangtise/token.json` | Token 缓存文件路径 |
+| `GANGTISE_PAGE_CONCURRENCY` | `5` | 分页并发数 |
+| `GANGTISE_VERBOSE` | — | 设为 `1` 开启请求耗时日志（输出到 stderr） |
+
+认证优先级：`GANGTISE_TOKEN` > Token 缓存文件 > `GANGTISE_ACCESS_KEY` + `GANGTISE_SECRET_KEY`（自动换取并缓存 Token）。
+
+## 开发
+
+```bash
+npm run dev      # 直接运行源码（tsx，无需 build）
+npm run build    # 编译 TypeScript → dist/
+npm test         # 运行测试
+```
+
+## License
+
+MIT

package/dist/core/asyncContent.js

@@ -0,0 +1,41 @@
+import { ApiError } from "./errors.js";
+import { AsyncTimeoutError } from "./errors.js";
+export const POLL_INITIAL_DELAY_MS = 5_000;
+export const POLL_MAX_DELAY_MS = 30_000;
+function nextDelayMs(attempt) {
+    // 5s, 8s, 13s, 20s, 30s, 30s, ...
+    const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
+    return Math.min(POLL_MAX_DELAY_MS, Math.round(grown));
+}
+function isAsyncPending(error) {
+    return error instanceof ApiError && error.code === "410110";
+}
+export async function pollAsyncContent(client, getContentEndpoint, dataId, timeoutMs = 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    while (true) {
+        attempt++;
+        try {
+            const result = await client.call(getContentEndpoint, { dataId });
+            if (result?.content != null) {
+                return { content: result.content };
+            }
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.code === "410111") {
+                throw error;
+            }
+            if (!isAsyncPending(error))
+                throw error;
+        }
+        const now = Date.now();
+        if (now >= deadline) {
+            throw new AsyncTimeoutError(dataId);
+        }
+        const delay = Math.min(nextDelayMs(attempt), deadline - now);
+        await new Promise(resolve => setTimeout(resolve, delay));
+        if (Date.now() >= deadline) {
+            throw new AsyncTimeoutError(dataId);
+        }
+    }
+}

package/dist/core/auth.js

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+export async function readTokenCache(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(content);
+        if (parsed && typeof parsed === "object" && typeof parsed.accessToken === "string" && typeof parsed.expiresAt === "number") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeTokenCache(filePath, cache) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(cache, null, 2), { encoding: "utf8", mode: 0o600 });
+}
+export function isTokenCacheValid(cache, bufferSeconds = 300) {
+    if (!cache?.accessToken || !cache.expiresAt) {
+        return false;
+    }
+    const now = Math.floor(Date.now() / 1000);
+    return cache.expiresAt - bufferSeconds > now;
+}
+export function normalizeToken(token) {
+    return token.startsWith("Bearer ") ? token : `Bearer ${token}`;
+}
+export function requireAccessCredentials(accessKey, secretKey) {
+    if (!accessKey || !secretKey) {
+        throw new ConfigError("Missing GANGTISE_ACCESS_KEY or GANGTISE_SECRET_KEY");
+    }
+    return { accessKey, secretKey };
+}

package/dist/core/client.js

@@ -0,0 +1,354 @@
+import { createWriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pipeline } from "node:stream/promises";
+import { request } from "undici";
+import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
+import { ApiError, ValidationError } from "./errors.js";
+import { ENDPOINTS } from "./endpoints.js";
+import { getLookupData } from "./lookupData/index.js";
+import { getDispatcher, isVerbose, logTiming, markRetryable, runWithConcurrency, withRetry } from "./transport.js";
+const PAGINATION_CONCURRENCY = Number(process.env.GANGTISE_PAGE_CONCURRENCY ?? 5) || 5;
+const AUTH_RETRY_CODES = new Set(["8000014", "8000015"]);
+export class GangtiseClient {
+    config;
+    refreshPromise = null;
+    memoCache = null;
+    constructor(config) {
+        this.config = config;
+    }
+    async getAuthorizationHeader(forceRefresh = false) {
+        if (this.config.token && !forceRefresh) {
+            return normalizeToken(this.config.token);
+        }
+        if (!forceRefresh) {
+            if (isTokenCacheValid(this.memoCache)) {
+                return normalizeToken(this.memoCache.accessToken);
+            }
+            const cache = await readTokenCache(this.config.tokenCachePath);
+            if (isTokenCacheValid(cache)) {
+                this.memoCache = cache;
+                return normalizeToken(cache.accessToken);
+            }
+        }
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.doTokenRefresh().finally(() => { this.refreshPromise = null; });
+        }
+        return this.refreshPromise;
+    }
+    async doTokenRefresh() {
+        const credentials = requireAccessCredentials(this.config.accessKey, this.config.secretKey);
+        const envelope = await this.requestJson(ENDPOINTS["auth.login"], {
+            accessKey: credentials.accessKey,
+            secretKey: credentials.secretKey,
+        }, false);
+        const accessToken = normalizeToken(envelope.accessToken);
+        const expiresAt = Math.floor(Date.now() / 1000) + envelope.expiresIn;
+        const cache = { ...envelope, accessToken, expiresAt };
+        this.memoCache = cache;
+        await writeTokenCache(this.config.tokenCachePath, cache);
+        return accessToken;
+    }
+    isEnvelope(parsed) {
+        if (!parsed || typeof parsed !== 'object')
+            return false;
+        const obj = parsed;
+        if (!('code' in obj))
+            return false;
+        return 'msg' in obj || 'data' in obj || 'success' in obj || 'status' in obj;
+    }
+    throwHttpError(parsed, statusCode) {
+        if (this.isEnvelope(parsed)) {
+            const code = parsed.code === undefined ? undefined : String(parsed.code);
+            throw new ApiError(parsed.msg || `API request failed (HTTP ${statusCode})`, code, statusCode, parsed);
+        }
+        throw new ApiError(`API request failed (HTTP ${statusCode})`, undefined, statusCode, parsed);
+    }
+    unwrapEnvelope(parsed, statusCode) {
+        if (!this.isEnvelope(parsed)) {
+            return parsed;
+        }
+        const code = parsed.code === undefined ? undefined : String(parsed.code);
+        const ok = parsed.status === true || parsed.success === true || code === "000000" || code === "0";
+        if (!ok) {
+            throw new ApiError(parsed.msg || "API request failed", code, statusCode, parsed);
+        }
+        if ('data' in parsed) {
+            return parsed.data;
+        }
+        return parsed;
+    }
+    async readLocalLookup(endpoint) {
+        const keyMapping = {
+            "lookup.research-areas.list": "research-areas",
+            "lookup.broker-orgs.list": "broker-orgs",
+            "lookup.meeting-orgs.list": "meeting-orgs",
+            "lookup.industries.list": "industries",
+            "lookup.regions.list": "regions",
+            "lookup.announcement-categories.list": "announcement-categories",
+            "lookup.industry-codes.list": "industry-codes",
+            "lookup.theme-ids.list": "theme-ids",
+        };
+        const lookupKey = keyMapping[endpoint.key];
+        if (lookupKey) {
+            return getLookupData(lookupKey);
+        }
+        throw new ApiError(`Unsupported local lookup endpoint: ${endpoint.key}`);
+    }
+    isPaginatedListResponse(value) {
+        return Boolean(value
+            && typeof value === 'object'
+            && typeof value.total === 'number'
+            && Array.isArray(value.list));
+    }
+    async requestPaginated(endpoint, body) {
+        const initialBody = body && typeof body === 'object' ? { ...body } : {};
+        if ('from' in initialBody && (typeof initialBody.from !== 'number' || !Number.isFinite(initialBody.from) || initialBody.from < 0)) {
+            throw new ValidationError('Invalid from: expected a non-negative number');
+        }
+        if ('size' in initialBody && initialBody.size !== undefined && (typeof initialBody.size !== 'number' || !Number.isFinite(initialBody.size) || initialBody.size <= 0)) {
+            throw new ValidationError('Invalid size: expected a positive number');
+        }
+        const startFrom = typeof initialBody.from === 'number' && Number.isFinite(initialBody.from) ? initialBody.from : 0;
+        const requestedSize = typeof initialBody.size === 'number' && Number.isFinite(initialBody.size) ? initialBody.size : undefined;
+        const maxPageSize = endpoint.pagination?.maxPageSize ?? requestedSize ?? 20;
+        // First page: serial — we need total before deciding how many more requests to fan out.
+        const firstPageSize = requestedSize === undefined ? maxPageSize : Math.min(maxPageSize, requestedSize);
+        const firstPage = await this.requestJson(endpoint, {
+            ...initialBody,
+            from: startFrom,
+            size: firstPageSize,
+        });
+        if (!this.isPaginatedListResponse(firstPage))
+            return firstPage;
+        const total = firstPage.total;
+        const collected = [...firstPage.list];
+        // Last page reached on first request
+        if (firstPage.list.length < firstPageSize) {
+            return {
+                ...firstPage,
+                total,
+                list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
+            };
+        }
+        const available = Math.max(total - startFrom, 0);
+        const target = requestedSize === undefined ? available : Math.min(requestedSize, available);
+        if (collected.length >= target) {
+            return {
+                ...firstPage,
+                total,
+                list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
+            };
+        }
+        const pageRequests = [];
+        let nextFrom = startFrom + firstPage.list.length;
+        const endFrom = startFrom + target;
+        while (nextFrom < endFrom) {
+            const remaining = endFrom - nextFrom;
+            const size = Math.min(maxPageSize, remaining);
+            pageRequests.push({ from: nextFrom, size });
+            nextFrom += size;
+        }
+        const MAX_PAGES = 1000;
+        if (pageRequests.length + 1 > MAX_PAGES) {
+            pageRequests.length = MAX_PAGES - 1;
+        }
+        let unexpectedShape = false;
+        let totalDrift = false;
+        const pages = await runWithConcurrency(pageRequests, PAGINATION_CONCURRENCY, async (req) => {
+            const page = await this.requestJson(endpoint, {
+                ...initialBody,
+                from: req.from,
+                size: req.size,
+            });
+            if (!this.isPaginatedListResponse(page)) {
+                unexpectedShape = true;
+                return [];
+            }
+            if (page.total !== total)
+                totalDrift = true;
+            return page.list;
+        });
+        for (const list of pages) {
+            if (list.length === 0)
+                continue;
+            collected.push(...list);
+        }
+        if (unexpectedShape && isVerbose()) {
+            process.stderr.write(`[gangtise] warning: a page response had unexpected shape; results may be incomplete\n`);
+        }
+        if (totalDrift && isVerbose()) {
+            process.stderr.write(`[gangtise] warning: 'total' changed across pages (data shifted during fetch)\n`);
+        }
+        return {
+            ...firstPage,
+            total,
+            list: requestedSize === undefined ? collected : collected.slice(0, requestedSize),
+        };
+    }
+    async login() {
+        const authorization = await this.getAuthorizationHeader();
+        const cache = await readTokenCache(this.config.tokenCachePath);
+        return {
+            authorization,
+            cache,
+        };
+    }
+    async requestJson(endpoint, body, useAuth = true) {
+        if (endpoint.path.startsWith('/guide/')) {
+            return this.readLocalLookup(endpoint);
+        }
+        const dispatcher = getDispatcher();
+        const url = new URL(endpoint.path, this.config.baseUrl);
+        let authRetried = false;
+        return withRetry(async () => {
+            const headers = {
+                'content-type': 'application/json',
+            };
+            if (useAuth) {
+                headers.Authorization = await this.getAuthorizationHeader();
+            }
+            const startedAt = Date.now();
+            const response = await request(url, {
+                method: endpoint.method,
+                headers,
+                body: endpoint.method === 'GET' ? undefined : JSON.stringify(body ?? {}),
+                headersTimeout: this.config.timeoutMs,
+                bodyTimeout: this.config.timeoutMs,
+                dispatcher,
+            });
+            const text = await response.body.text();
+            logTiming(`${endpoint.method} ${endpoint.path}`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                const message = response.statusCode >= 400
+                    ? `API request failed (HTTP ${response.statusCode})`
+                    : 'Failed to parse API response';
+                throw new ApiError(message, undefined, response.statusCode, text.slice(0, 500));
+            }
+            if (response.statusCode >= 400) {
+                this.throwHttpError(parsed, response.statusCode);
+            }
+            try {
+                return this.unwrapEnvelope(parsed, response.statusCode);
+            }
+            catch (error) {
+                // Auto-recover from auth errors by forcing a token refresh once.
+                if (useAuth
+                    && !authRetried
+                    && error instanceof ApiError
+                    && error.code
+                    && AUTH_RETRY_CODES.has(error.code)
+                    && (this.config.accessKey && this.config.secretKey)) {
+                    authRetried = true;
+                    this.memoCache = null;
+                    await this.getAuthorizationHeader(true);
+                    throw markRetryable(new ApiError(error.message, error.code, error.statusCode, error.details));
+                }
+                throw error;
+            }
+        }, {
+            onRetry: (attempt, error, delay) => {
+                if (!isVerbose())
+                    return;
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`[gangtise] retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
+            },
+        });
+    }
+    async download(endpoint, query, options) {
+        const dispatcher = getDispatcher();
+        const url = new URL(endpoint.path, this.config.baseUrl);
+        Object.entries(query).forEach(([key, value]) => {
+            url.searchParams.set(key, String(value));
+        });
+        return withRetry(async () => {
+            const authorization = await this.getAuthorizationHeader();
+            const startedAt = Date.now();
+            const response = await request(url, {
+                method: endpoint.method,
+                headers: { Authorization: authorization },
+                headersTimeout: this.config.timeoutMs,
+                bodyTimeout: this.config.timeoutMs,
+                dispatcher,
+            });
+            const contentType = Array.isArray(response.headers['content-type']) ? response.headers['content-type'][0] : response.headers['content-type'];
+            if (contentType?.includes('application/json')) {
+                const text = await response.body.text();
+                logTiming(`GET ${endpoint.path} (json)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    if (response.statusCode >= 400) {
+                        throw new ApiError('Download failed', undefined, response.statusCode, text);
+                    }
+                    return { text, contentType };
+                }
+                if (response.statusCode >= 400) {
+                    this.throwHttpError(parsed, response.statusCode);
+                }
+                const data = this.unwrapEnvelope(parsed, response.statusCode);
+                if (data && typeof data === 'object' && 'url' in data && typeof data.url === 'string') {
+                    return { url: String(data.url), contentType };
+                }
+                return { text: JSON.stringify(data, null, 2), contentType };
+            }
+            if (contentType?.includes('text/plain') || contentType?.includes('text/html')) {
+                const text = await response.body.text();
+                logTiming(`GET ${endpoint.path} (text)`, Date.now() - startedAt, `${response.statusCode}, ${text.length}B`);
+                if (response.statusCode >= 400) {
+                    throw new ApiError('Download failed', undefined, response.statusCode, text);
+                }
+                return { text, contentType };
+            }
+            if (response.statusCode >= 400) {
+                const text = await response.body.text();
+                throw new ApiError('Download failed', undefined, response.statusCode, text);
+            }
+            const contentDisposition = response.headers['content-disposition'];
+            const filenameMatch = Array.isArray(contentDisposition)
+                ? contentDisposition[0]?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i)
+                : contentDisposition?.match(/filename\*=UTF-8''([^;]+)|filename="?([^";]+)"?/i);
+            const filename = filenameMatch ? decodeURIComponent(filenameMatch[1] || filenameMatch[2]) : undefined;
+            // Stream directly to disk when caller already knows the destination
+            if (options?.streamTo) {
+                await fs.mkdir(path.dirname(options.streamTo), { recursive: true });
+                await pipeline(response.body, createWriteStream(options.streamTo));
+                logTiming(`GET ${endpoint.path} (stream)`, Date.now() - startedAt, `${response.statusCode}`);
+                return { contentType, filename, savedPath: options.streamTo };
+            }
+            const buffer = await response.body.arrayBuffer();
+            logTiming(`GET ${endpoint.path} (binary)`, Date.now() - startedAt, `${response.statusCode}, ${buffer.byteLength}B`);
+            return {
+                data: new Uint8Array(buffer),
+                contentType,
+                filename,
+            };
+        }, {
+            onRetry: (attempt, error, delay) => {
+                if (!isVerbose())
+                    return;
+                const msg = error instanceof Error ? error.message : String(error);
+                process.stderr.write(`[gangtise] download retry ${attempt} after ${delay.toFixed(0)}ms: ${msg.slice(0, 120)}\n`);
+            },
+        });
+    }
+    async call(endpointKey, body, query, options) {
+        const endpoint = ENDPOINTS[endpointKey];
+        if (!endpoint) {
+            throw new ApiError(`Unknown endpoint key: ${endpointKey}`);
+        }
+        if (endpoint.kind === 'download') {
+            return this.download(endpoint, query ?? {}, options);
+        }
+        if (endpoint.kind === 'json' && endpoint.pagination?.enabled) {
+            return this.requestPaginated(endpoint, body);
+        }
+        return this.requestJson(endpoint, body);
+    }
+}

package/dist/core/config.js

@@ -0,0 +1,21 @@
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_BASE_URL = "https://open.gangtise.com";
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_TOKEN_CACHE_PATH = path.join(os.homedir(), ".config", "gangtise", "token.json");
+export const DEFAULT_ASYNC_TIMEOUT_MS = 180_000;
+export function loadConfig() {
+    const timeoutValue = process.env.GANGTISE_TIMEOUT_MS;
+    const timeoutMs = timeoutValue ? Number(timeoutValue) : DEFAULT_TIMEOUT_MS;
+    const asyncTimeoutValue = process.env.GANGTISE_MCP_ASYNC_TIMEOUT_MS;
+    const asyncTimeoutMs = asyncTimeoutValue ? Number(asyncTimeoutValue) : DEFAULT_ASYNC_TIMEOUT_MS;
+    return {
+        baseUrl: process.env.GANGTISE_BASE_URL ?? DEFAULT_BASE_URL,
+        timeoutMs: Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : DEFAULT_TIMEOUT_MS,
+        accessKey: process.env.GANGTISE_ACCESS_KEY,
+        secretKey: process.env.GANGTISE_SECRET_KEY,
+        token: process.env.GANGTISE_TOKEN,
+        tokenCachePath: process.env.GANGTISE_TOKEN_CACHE_PATH ?? DEFAULT_TOKEN_CACHE_PATH,
+        asyncTimeoutMs: Number.isFinite(asyncTimeoutMs) && asyncTimeoutMs > 0 ? asyncTimeoutMs : DEFAULT_ASYNC_TIMEOUT_MS,
+    };
+}

package/dist/core/download.js

@@ -0,0 +1,69 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DownloadError } from "./errors.js";
+const MIME_EXT = {
+    "application/pdf": ".pdf",
+    "application/msword": ".doc",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+    "application/vnd.ms-excel": ".xls",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+    "application/vnd.ms-powerpoint": ".ppt",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+    "application/zip": ".zip",
+    "application/json": ".json",
+    "text/plain": ".txt",
+    "text/html": ".html",
+    "text/csv": ".csv",
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "application/octet-stream": ".bin",
+};
+function extFromContentType(contentType) {
+    if (!contentType)
+        return ".bin";
+    const mime = contentType.split(";")[0].trim().toLowerCase();
+    return MIME_EXT[mime] ?? ".bin";
+}
+/**
+ * Downloads a file via the Gangtise client and returns a structured result.
+ * For binary files, streams to a unique temp directory (not auto-cleaned).
+ */
+export async function downloadToResult(client, endpoint, query) {
+    // For binary downloads, generate a unique temp dir first
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "gangtise-mcp-"));
+    const tempPath = path.join(tempDir, "download.bin");
+    const raw = await client.download(endpoint, query, { streamTo: tempPath });
+    // Case 1: API returned a redirect/presigned URL
+    if (raw.url) {
+        // Clean up the unused temp file
+        await fs.rm(tempDir, { recursive: true, force: true });
+        return { url: raw.url, filename: raw.filename };
+    }
+    // Case 2: Text content (Markdown, HTML, plain text)
+    if (raw.text != null) {
+        await fs.rm(tempDir, { recursive: true, force: true });
+        return { text: raw.text, filename: raw.filename, contentType: raw.contentType };
+    }
+    // Case 3: Streamed to disk (binary)
+    if (raw.savedPath) {
+        const ext = extFromContentType(raw.contentType);
+        const filename = raw.filename ?? `download${ext}`;
+        // Rename to meaningful extension if needed
+        const finalPath = path.join(tempDir, filename);
+        if (finalPath !== raw.savedPath) {
+            await fs.rename(raw.savedPath, finalPath);
+        }
+        return { savedPath: finalPath, filename, contentType: raw.contentType };
+    }
+    // Case 4: In-memory binary (fallback for small files)
+    if (raw.data) {
+        const ext = extFromContentType(raw.contentType);
+        const filename = raw.filename ?? `download${ext}`;
+        const finalPath = path.join(tempDir, filename);
+        await fs.writeFile(finalPath, raw.data);
+        return { savedPath: finalPath, filename, contentType: raw.contentType };
+    }
+    await fs.rm(tempDir, { recursive: true, force: true });
+    throw new DownloadError("Unexpected download response: no url, text, or binary data");
+}