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();

各メソッド、リクエストパラメーター、レスポンスフィールドのドキュメントは docstring に記載されており、ほとんどの最新エディターでホバーすると表示されます。

エラーの処理

ライブラリが 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 の内部エラーは、すべてデフォルトで再試行されます。

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 がスローされます。

タイムアウトしたリクエストは、デフォルトで 2 回再試行されます。

高度な使用方法

生の 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);

ロギング

重要

すべてのログメッセージは、デバッグのみを目的としています。ログメッセージの形式や内容は、 リリースによって変更される場合があります。

ログレベル

ログレベルは、次の 2 つの方法で設定できます。

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 関数を使う場合は、グローバル関数をポリフィルできます。

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 をサポートしています。

以下のランタイムをサポートしています。

• ウェブブラウザー（最新の Chrome、Firefox、Safari、Edge など）
• Node.js 20 LTS 以降のサポート期間が終了していないバージョン。
• Deno v1.28.0 以降。
• Bun 1.0 以降。
• Cloudflare Workers。
• Vercel Edge Runtime。
• "node"環境の Jest 28 以降（現時点では"jsdom"はサポートされていません）。
• Nitro v2.6 以降。

現時点では React Native はサポートされていません。

その他のランタイム環境に関心がある場合は、GitHub で issue を作成するか、既存の issue に賛成票を投じてください。

コントリビューション

コントリビューションに関するドキュメントをご覧ください。