Stainless Topiclake Mcp Server

Stainless Topiclake Mcp Server TypeScript API 库

此库可让你在服务端 TypeScript 或 JavaScript 中便捷地使用 Stainless Topiclake Mcp Server REST API。

此库的完整 API 参见 api.md。

此库由 Stainless 生成。

安装

npm install stainless_topiclake_mcp_server

使用

此库的完整 API 参见 api.md。

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';

const client = new StainlessTopiclakeMcpServer({
  apiKey: process.env['API_KEY'], // This is the default and can be omitted
});

const response = await client.policyinsights.us.export.api.v1.getDocuments();

console.log(response.count);

请求和响应类型

此库包含所有请求参数和响应字段的 TypeScript 定义。你可以按如下方式导入和使用：

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';

const client = new StainlessTopiclakeMcpServer({
  apiKey: process.env['API_KEY'], // This is the default and can be omitted
});

const response: StainlessTopiclakeMcpServer.Policyinsights.Us.Export.API.V1GetDocumentsResponse =
  await client.policyinsights.us.export.api.v1.getDocuments();

每个方法、请求参数和响应字段的文档都可在文档字符串中查看，并会在大多数现代编辑器中悬停时显示。

错误处理

当此库无法连接到 API， 或 API 返回非成功状态码（即 4xx 或 5xx 响应）时， 会抛出 APIError 的子类：

const response = await client.policyinsights.us.export.api.v1.getDocuments().catch(async (err) => {
  if (err instanceof StainlessTopiclakeMcpServer.APIError) {
    console.log(err.status); // 400
    console.log(err.name); // BadRequestError
    console.log(err.headers); // {server: 'nginx', ...}
  } else {
    throw err;
  }
});

错误代码如下：

状态码	错误类型
400	BadRequestError
401	AuthenticationError
403	PermissionDeniedError
404	NotFoundError
422	UnprocessableEntityError
429	RateLimitError
>=500	InternalServerError
N/A	APIConnectionError

重试

某些错误默认会自动重试 2 次，并采用较短的指数退避。 连接错误（例如网络连接问题导致的错误）、408 Request Timeout、409 Conflict、 429 Rate Limit 和 >=500 Internal errors 默认都会重试。

你可以使用 maxRetries 选项进行配置或禁用重试：

// Configure the default for all requests:
const client = new StainlessTopiclakeMcpServer({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.policyinsights.us.export.api.v1.getDocuments({
  maxRetries: 5,
});

超时

请求默认在 1 分钟后超时。你可以使用 timeout 选项进行配置：

// Configure the default for all requests:
const client = new StainlessTopiclakeMcpServer({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.policyinsights.us.export.api.v1.getDocuments({
  timeout: 5 * 1000,
});

超时时会抛出 APIConnectionTimeoutError。

请注意，超时的请求默认会重试两次。

高级用法

访问原始 Response 数据（例如，标头）

可通过所有方法返回的 APIPromise 类型上的 .asResponse() 方法访问 fetch() 返回的“原始” Response。 此方法会在收到成功响应的标头后立即返回，且不会读取响应正文，因此你可以自由编写自定义解析或流处理逻辑。

你也可以使用 .withResponse() 方法，获取原始 Response 及解析后的数据。 与 .asResponse() 不同，此方法会读取正文，并在解析完成后返回。

const client = new StainlessTopiclakeMcpServer();

const response = await client.policyinsights.us.export.api.v1.getDocuments().asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: response, response: raw } = await client.policyinsights.us.export.api.v1
  .getDocuments()
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(response.count);

日志记录

重要

所有日志消息仅用于调试。日志消息的格式和内容 可能会随版本发布而变化。

日志级别

可以通过两种方式配置日志级别：

1. 通过 STAINLESS_TOPICLAKE_MCP_SERVER_LOG 环境变量
2. 使用 logLevel 客户端选项（设置后会覆盖环境变量）

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';

const client = new StainlessTopiclakeMcpServer({
  logLevel: 'debug', // Show all log messages
});

可用日志级别，从详细到简略依次为：

• 'debug' - 显示调试消息、信息、警告和错误
• 'info' - 显示信息、警告和错误
• 'warn' - 显示警告和错误（默认）
• 'error' - 仅显示错误
• 'off' - 禁用所有日志记录

在 'debug' 级别下，会记录所有 HTTP 请求和响应，包括标头和正文。 部分与身份验证相关的标头会被隐藏，但请求和响应正文中的敏感数据 仍可能会显示。

自定义日志记录器

默认情况下，此库会将日志记录到 globalThis.console。你也可以提供自定义日志记录器。 支持大多数日志记录库，包括 pino、winston、bunyan、consola、signale 和 @std/log。如果你的日志记录器无法正常工作，请提交一个 issue。

提供自定义日志记录器时，logLevel 选项仍会控制输出哪些消息，低于配置级别的消息不会发送到日志记录器。

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';
import pino from 'pino';

const logger = pino();

const client = new StainlessTopiclakeMcpServer({
  logger: logger.child({ name: 'StainlessTopiclakeMcpServer' }),
  logLevel: 'debug', // Send all messages to pino, allowing it to filter
});

发起自定义／未记录的请求

此库经过类型定义，可便捷地访问有文档说明的 API。如果你需要访问未记录的端点、参数或响应属性，仍然可以使用此库。

未记录的端点

若要向未记录的端点发送请求，可以使用 client.get、client.post 和其他 HTTP 方法。 发起这些请求时，客户端上的选项（例如重试）仍会生效。

await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});

未记录的请求参数

若要使用未记录的参数发起请求，可以在未记录的参数上使用 // @ts-expect-error。此库不会在运行时验证请求是否符合类型定义，因此你发送的任何额外值都会原样发送。

client.policyinsights.us.export.api.v1.getDocuments({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});

对于使用 GET 方法的请求，所有额外参数都会放在查询字符串中；其他请求则会将额外参数放在请求正文中。

如果要显式发送额外参数，可以使用 query、body 和 headers 请求选项。

未记录的响应属性

若要访问未记录的响应属性，可以在响应对象上使用 // @ts-expect-error，也可以将响应对象转换为所需类型。与请求参数一样，我们不会验证或移除 API 响应中的额外属性。

自定义 fetch 客户端

默认情况下，此库要求定义全局 fetch 函数。

如果要使用其他 fetch 函数，可以为全局函数添加 polyfill：

import fetch from 'my-fetch';

globalThis.fetch = fetch;

也可以将其传递给客户端：

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';
import fetch from 'my-fetch';

const client = new StainlessTopiclakeMcpServer({ fetch });

Fetch 选项

如果要设置自定义 fetch 选项而不覆盖 fetch 函数，可以在实例化客户端或发起请求时提供 fetchOptions 对象。（请求专用选项会覆盖客户端选项。）

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';

const client = new StainlessTopiclakeMcpServer({
  fetchOptions: {
    // `RequestInit` options
  },
});

配置代理

若要修改代理行为，可以提供自定义 fetchOptions，为请求添加特定于运行时的代理选项：

Node ^[文档]

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new StainlessTopiclakeMcpServer({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

Bun ^[文档]

import StainlessTopiclakeMcpServer from 'stainless_topiclake_mcp_server';

const client = new StainlessTopiclakeMcpServer({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

Deno ^[文档]

import StainlessTopiclakeMcpServer from 'npm:stainless_topiclake_mcp_server';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new StainlessTopiclakeMcpServer({
  fetchOptions: {
    client: httpClient,
  },
});

常见问题

语义化版本

此软件包通常遵循 SemVer 约定，但某些不向后兼容的变更可能会作为次要版本发布：

1. 仅影响静态类型、不会破坏运行时行为的变更。
2. 对库内部实现的变更；这些实现虽然在技术上是公开的，但并非供外部使用，也没有相关文档。（如果你依赖此类内部实现，请创建 GitHub issue 告知我们。）
3. 我们预计实际上不会影响绝大多数用户的变更。

我们非常重视向后兼容性，并努力确保你可以顺利升级。

我们期待收到你的反馈；如有问题、错误报告或建议，请创建 issue。

要求

支持 TypeScript >= 4.9。

支持以下运行时：

• Web 浏览器（最新版 Chrome、Firefox、Safari、Edge 等）
• Node.js 20 LTS 或更高版本（未结束生命周期的版本）。
• Deno v1.28.0 或更高版本。
• Bun 1.0 或更高版本。
• Cloudflare Workers。
• Vercel Edge Runtime。
• Jest 28 或更高版本，且环境为 "node"（目前不支持 "jsdom"）。
• Nitro v2.6 或更高版本。

请注意，目前不支持 React Native。

如果你有意支持其他运行时环境，请在 GitHub 上创建 issue 或为现有 issue 投票。

贡献

请参阅贡献文档。