@arikusi/deepseek-mcp-server 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -16,6 +16,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Nothing yet
 
+## [1.3.0] - 2026-03-04
+
+### Added
+- **Multi-Turn Sessions**: `session_id` parameter on `deepseek_chat` for multi-turn conversations. Session history is stored in memory and automatically prepended to requests. Sessions have configurable TTL and max count.
+- **Session Management Tool**: `deepseek_sessions` tool with `list`, `delete`, and `clear` actions for managing active sessions.
+- **Circuit Breaker**: Protects against cascading API failures. After 5 consecutive failures, fast-fails for 30 seconds, then probes for recovery.
+- **Model Fallback**: Automatic fallback between `deepseek-chat` and `deepseek-reasoner` on retryable errors (429, 503, timeout). Configurable via `FALLBACK_ENABLED`.
+- **MCP Resources**: 3 read-only resources following MCP Resources spec:
+  - `deepseek://models`: Model list with capabilities, context limits, and pricing
+  - `deepseek://config`: Current server configuration (API key masked)
+  - `deepseek://usage`: Real-time usage statistics (requests, tokens, costs, sessions)
+- **Usage Tracker**: Global usage statistics tracking across all requests.
+- **New Error Classes**: `FallbackExhaustedError`, `CircuitBreakerOpenError` for resilience error handling.
+- **New Config**: `SESSION_TTL_MINUTES` (default: 30), `MAX_SESSIONS` (default: 100), `FALLBACK_ENABLED` (default: true).
+- **198 Tests**: Up from 150, covering sessions, circuit breaker, fallback, and MCP resources.
+
+### Changed
+- `deepseek-client.ts` now wraps API calls in circuit breaker and supports automatic model fallback.
+- `deepseek_chat` tool description updated to mention sessions, fallback, and circuit breaker.
+- `tools/index.ts` now registers both `deepseek_chat` and `deepseek_sessions` tools.
+- `index.ts` now registers MCP resources via `registerAllResources()`.
+
 ## [1.2.0] - 2026-02-26
 
 ### Added
@@ -171,6 +193,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Version History
 
+- **1.3.0** (2026-03-04): Sessions, circuit breaker, model fallback, MCP resources, 198 tests
 - **1.2.0** (2026-02-26): DeepSeek V3.2 support — thinking mode, JSON mode, cache-aware pricing, 150 tests
 - **1.1.1** (2026-02-11): Modular architecture, type safety, security fixes, 126 tests
 - **1.1.0** (2026-02-10): Function calling, config system, test suite
@@ -184,7 +207,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [GitHub repository](https://github.com/arikusi/deepseek-mcp-server)
 - [Issue tracker](https://github.com/arikusi/deepseek-mcp-server/issues)
 
-[Unreleased]: https://github.com/arikusi/deepseek-mcp-server/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/arikusi/deepseek-mcp-server/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/arikusi/deepseek-mcp-server/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/arikusi/deepseek-mcp-server/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/arikusi/deepseek-mcp-server/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/arikusi/deepseek-mcp-server/compare/v1.0.3...v1.1.0

package/README.md

@@ -7,12 +7,12 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 [![Build Status](https://github.com/arikusi/deepseek-mcp-server/workflows/CI/badge.svg)](https://github.com/arikusi/deepseek-mcp-server/actions)
 
-A Model Context Protocol (MCP) server that integrates DeepSeek AI models with MCP-compatible clients. Access DeepSeek's powerful chat and reasoning models directly from your development environment.
+A Model Context Protocol (MCP) server that integrates DeepSeek AI models with MCP-compatible clients. Access DeepSeek's powerful chat and reasoning models with multi-turn sessions, automatic model fallback, and MCP Resources directly from your development environment.
 
 **Compatible with:**
 - Claude Code CLI
-- Gemini CLI (if MCP support is available)
-- Any MCP-compatible client
+- Gemini CLI
+- Any MCP-compatible client (Cursor, Windsurf, etc.)
 
 > **Note**: This is an unofficial community project and is not affiliated with DeepSeek.
 
@@ -49,14 +49,18 @@ That's it! Your MCP client can now use DeepSeek models!
 ## Features
 
 - **DeepSeek V3.2**: Both models now run DeepSeek-V3.2 (since Sept 2025)
+- **Multi-Turn Sessions**: Conversation context preserved across requests via `session_id` parameter
+- **Model Fallback & Circuit Breaker**: Automatic fallback between models with circuit breaker protection against cascading failures
+- **MCP Resources**: `deepseek://models`, `deepseek://config`, `deepseek://usage` — query model info, config, and usage stats
 - **Thinking Mode**: Enable enhanced reasoning on deepseek-chat with `thinking: {type: "enabled"}`
 - **JSON Output Mode**: Structured JSON responses with `json_mode: true`
 - **Function Calling**: OpenAI-compatible tool use with up to 128 tool definitions
 - **Cache-Aware Cost Tracking**: Automatic cost calculation with cache hit/miss breakdown
+- **Session Management Tool**: List, delete, and clear sessions via `deepseek_sessions` tool
 - **Configurable**: Environment-based configuration with validation
 - **12 Prompt Templates**: Pre-built templates for debugging, code review, function calling, and more
 - **Streaming Support**: Real-time response generation
-- **Tested**: 150 tests with 90%+ code coverage
+- **Tested**: 198 tests with 90%+ code coverage
 - **Type-Safe**: Full TypeScript implementation
 - **MCP Compatible**: Works with any MCP-compatible CLI (Claude Code, Gemini CLI, etc.)
 
@@ -98,7 +102,7 @@ npm run build
 
 ## Usage
 
-Once configured, your MCP client will have access to the `deepseek_chat` tool and can use DeepSeek models.
+Once configured, your MCP client will have access to `deepseek_chat` and `deepseek_sessions` tools, plus 3 MCP resources.
 
 **Example prompts:**
 ```
@@ -150,6 +154,7 @@ Chat with DeepSeek AI models with automatic cost tracking and function calling s
 - `tool_choice` (optional): "auto" | "none" | "required" | `{type: "function", function: {name: "..."}}`
 - `thinking` (optional): Enable thinking mode `{type: "enabled"}` for enhanced reasoning
 - `json_mode` (optional): Enable JSON output mode (supported by both models)
+- `session_id` (optional): Session ID for multi-turn conversations. Previous context is automatically prepended.
 
 **Response includes:**
 - Content with formatting
@@ -258,6 +263,60 @@ When thinking mode is enabled, `temperature`, `top_p`, `frequency_penalty`, and
 
 JSON mode ensures the model outputs valid JSON. Include the word "json" in your prompt for best results. Supported by both `deepseek-chat` and `deepseek-reasoner`.
 
+**Multi-Turn Session Example:**
+
+```json
+{
+  "messages": [
+    {
+      "role": "user",
+      "content": "What is the capital of France?"
+    }
+  ],
+  "session_id": "my-session-1"
+}
+```
+
+Use the same `session_id` across requests to maintain conversation context. The server stores messages in memory and automatically prepends history to each request.
+
+### `deepseek_sessions`
+
+Manage conversation sessions.
+
+**Parameters:**
+- `action` (required): "list" | "clear" | "delete"
+- `session_id` (optional): Required when action is "delete"
+
+**Examples:**
+```json
+{"action": "list"}
+{"action": "delete", "session_id": "my-session-1"}
+{"action": "clear"}
+```
+
+## Available Resources
+
+MCP Resources provide read-only data about the server:
+
+| Resource URI | Description |
+|-------------|-------------|
+| `deepseek://models` | Available models with capabilities, context limits, and pricing |
+| `deepseek://config` | Current server configuration (API key masked) |
+| `deepseek://usage` | Real-time usage statistics (requests, tokens, costs, sessions) |
+
+## Model Fallback & Circuit Breaker
+
+When a model fails with a retryable error (429, 503, timeout), the server automatically falls back to the other model:
+- `deepseek-chat` fails → tries `deepseek-reasoner`
+- `deepseek-reasoner` fails → tries `deepseek-chat`
+
+The circuit breaker protects against cascading failures:
+- After 5 consecutive failures, the circuit **opens** (fast-fail mode)
+- After 30 seconds, it enters **half-open** state and sends a probe request
+- If the probe succeeds, the circuit **closes** and normal operation resumes
+
+Fallback can be disabled with `FALLBACK_ENABLED=false`.
+
 ## Available Prompts
 
 Pre-built prompt templates for common tasks (12 total):
@@ -320,6 +379,9 @@ The server is configured via environment variables. All settings except `DEEPSEE
 | `MAX_RETRIES` | `2` | Maximum retry count for failed requests |
 | `SKIP_CONNECTION_TEST` | `false` | Skip startup API connection test |
 | `MAX_MESSAGE_LENGTH` | `100000` | Maximum message content length (characters) |
+| `SESSION_TTL_MINUTES` | `30` | Session time-to-live in minutes |
+| `MAX_SESSIONS` | `100` | Maximum number of concurrent sessions |
+| `FALLBACK_ENABLED` | `true` | Enable automatic model fallback on errors |
 
 **Example with custom config:**
 ```bash
@@ -336,17 +398,26 @@ claude mcp add -s user deepseek npx @arikusi/deepseek-mcp-server \
 ```
 deepseek-mcp-server/
 ├── src/
-│   ├── index.ts              # Entry point, bootstrap (~80 lines)
+│   ├── index.ts              # Entry point, bootstrap
 │   ├── server.ts             # McpServer factory (auto-version)
-│   ├── deepseek-client.ts    # DeepSeek API wrapper (OpenAI SDK)
+│   ├── deepseek-client.ts    # DeepSeek API wrapper (circuit breaker + fallback)
 │   ├── config.ts             # Centralized config with Zod validation
 │   ├── cost.ts               # Cost calculation and formatting
 │   ├── schemas.ts            # Zod input validation schemas
 │   ├── types.ts              # TypeScript types + type guards
 │   ├── errors.ts             # Custom error classes
+│   ├── session.ts            # In-memory session store (multi-turn)
+│   ├── circuit-breaker.ts    # Circuit breaker pattern
+│   ├── usage-tracker.ts      # Usage statistics tracker
 │   ├── tools/
-│   │   ├── deepseek-chat.ts  # deepseek_chat tool handler
+│   │   ├── deepseek-chat.ts  # deepseek_chat tool (sessions + fallback)
+│   │   ├── deepseek-sessions.ts # deepseek_sessions tool
 │   │   └── index.ts          # Tool registration aggregator
+│   ├── resources/
+│   │   ├── models.ts         # deepseek://models resource
+│   │   ├── config.ts         # deepseek://config resource
+│   │   ├── usage.ts          # deepseek://usage resource
+│   │   └── index.ts          # Resource registration aggregator
 │   └── prompts/
 │       ├── core.ts           # 5 core reasoning prompts
 │       ├── advanced.ts       # 5 advanced prompts

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Circuit Breaker Pattern
+ * Prevents cascading failures by fast-failing when the API is unhealthy
+ *
+ * States:
+ *   CLOSED  → normal operation, requests pass through
+ *   OPEN    → API is unhealthy, requests are immediately rejected
+ *   HALF_OPEN → testing if API has recovered with a single probe request
+ */
+import type { CircuitBreakerStatus } from './types.js';
+export declare class CircuitBreaker {
+    private readonly threshold;
+    private readonly openTimeout;
+    private state;
+    private failureCount;
+    private lastFailureTime;
+    private halfOpenInProgress;
+    constructor(threshold?: number, openTimeout?: number);
+    /**
+     * Execute a function through the circuit breaker.
+     * - CLOSED: pass through, track failures
+     * - OPEN: reject immediately (fast-fail) unless timeout elapsed → HALF_OPEN
+     * - HALF_OPEN: allow one probe request
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get current circuit breaker status
+     */
+    getStatus(): CircuitBreakerStatus;
+    /**
+     * Manually reset the circuit breaker to CLOSED state
+     */
+    reset(): void;
+    private onSuccess;
+    private onFailure;
+}
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAuB,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE5E,qBAAa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,kBAAkB,CAAS;gBAGhB,SAAS,GAAE,MAAU,EACrB,WAAW,GAAE,MAAc;IAG9C;;;;;OAKG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA+BlD;;OAEG;IACH,SAAS,IAAI,oBAAoB;IAiBjC;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,SAAS;CAYlB"}

package/dist/circuit-breaker.js

@@ -0,0 +1,101 @@
+/**
+ * Circuit Breaker Pattern
+ * Prevents cascading failures by fast-failing when the API is unhealthy
+ *
+ * States:
+ *   CLOSED  → normal operation, requests pass through
+ *   OPEN    → API is unhealthy, requests are immediately rejected
+ *   HALF_OPEN → testing if API has recovered with a single probe request
+ */
+import { CircuitBreakerOpenError } from './errors.js';
+export class CircuitBreaker {
+    threshold;
+    openTimeout;
+    state = 'CLOSED';
+    failureCount = 0;
+    lastFailureTime = 0;
+    halfOpenInProgress = false;
+    constructor(threshold = 5, openTimeout = 30000) {
+        this.threshold = threshold;
+        this.openTimeout = openTimeout;
+    }
+    /**
+     * Execute a function through the circuit breaker.
+     * - CLOSED: pass through, track failures
+     * - OPEN: reject immediately (fast-fail) unless timeout elapsed → HALF_OPEN
+     * - HALF_OPEN: allow one probe request
+     */
+    async execute(fn) {
+        if (this.state === 'OPEN') {
+            // Check if enough time has elapsed to try half-open
+            if (Date.now() - this.lastFailureTime >= this.openTimeout) {
+                this.state = 'HALF_OPEN';
+                this.halfOpenInProgress = false;
+            }
+            else {
+                throw new CircuitBreakerOpenError();
+            }
+        }
+        if (this.state === 'HALF_OPEN' && this.halfOpenInProgress) {
+            throw new CircuitBreakerOpenError('Circuit breaker is half-open — probe request in progress');
+        }
+        if (this.state === 'HALF_OPEN') {
+            this.halfOpenInProgress = true;
+        }
+        try {
+            const result = await fn();
+            this.onSuccess();
+            return result;
+        }
+        catch (error) {
+            this.onFailure();
+            throw error;
+        }
+    }
+    /**
+     * Get current circuit breaker status
+     */
+    getStatus() {
+        // Auto-transition from OPEN to HALF_OPEN if timeout elapsed
+        if (this.state === 'OPEN' &&
+            Date.now() - this.lastFailureTime >= this.openTimeout) {
+            this.state = 'HALF_OPEN';
+            this.halfOpenInProgress = false;
+        }
+        return {
+            state: this.state,
+            failureCount: this.failureCount,
+            lastFailureTime: this.lastFailureTime,
+        };
+    }
+    /**
+     * Manually reset the circuit breaker to CLOSED state
+     */
+    reset() {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.lastFailureTime = 0;
+        this.halfOpenInProgress = false;
+    }
+    onSuccess() {
+        if (this.state === 'HALF_OPEN') {
+            // Probe succeeded → close circuit
+            this.state = 'CLOSED';
+            this.halfOpenInProgress = false;
+        }
+        this.failureCount = 0;
+    }
+    onFailure() {
+        this.failureCount++;
+        this.lastFailureTime = Date.now();
+        if (this.state === 'HALF_OPEN') {
+            // Probe failed → re-open
+            this.state = 'OPEN';
+            this.halfOpenInProgress = false;
+        }
+        else if (this.failureCount >= this.threshold) {
+            this.state = 'OPEN';
+        }
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

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

package/dist/config.d.ts

@@ -11,6 +11,9 @@ declare const ConfigSchema: z.ZodObject<{
     maxRetries: z.ZodDefault<z.ZodNumber>;
     skipConnectionTest: z.ZodDefault<z.ZodBoolean>;
     maxMessageLength: z.ZodDefault<z.ZodNumber>;
+    sessionTtlMinutes: z.ZodDefault<z.ZodNumber>;
+    maxSessions: z.ZodDefault<z.ZodNumber>;
+    fallbackEnabled: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     apiKey: string;
     baseUrl: string;
@@ -19,6 +22,9 @@ declare const ConfigSchema: z.ZodObject<{
     maxRetries: number;
     skipConnectionTest: boolean;
     maxMessageLength: number;
+    sessionTtlMinutes: number;
+    maxSessions: number;
+    fallbackEnabled: boolean;
 }, {
     apiKey: string;
     baseUrl?: string | undefined;
@@ -27,6 +33,9 @@ declare const ConfigSchema: z.ZodObject<{
     maxRetries?: number | undefined;
     skipConnectionTest?: boolean | undefined;
     maxMessageLength?: number | undefined;
+    sessionTtlMinutes?: number | undefined;
+    maxSessions?: number | undefined;
+    fallbackEnabled?: boolean | undefined;
 }>;
 export type Config = z.infer<typeof ConfigSchema>;
 /**

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAQhB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAIlD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAqCnC;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWhB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAIlD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CA4CnC;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/config.js

@@ -12,6 +12,9 @@ const ConfigSchema = z.object({
     maxRetries: z.number().min(0).max(10).default(2),
     skipConnectionTest: z.boolean().default(false),
     maxMessageLength: z.number().positive().default(100_000),
+    sessionTtlMinutes: z.number().positive().default(30),
+    maxSessions: z.number().positive().default(100),
+    fallbackEnabled: z.boolean().default(true),
 });
 let cachedConfig = null;
 /**
@@ -34,6 +37,13 @@ export function loadConfig() {
         maxMessageLength: process.env.MAX_MESSAGE_LENGTH
             ? parseInt(process.env.MAX_MESSAGE_LENGTH, 10)
             : 100_000,
+        sessionTtlMinutes: process.env.SESSION_TTL_MINUTES
+            ? parseInt(process.env.SESSION_TTL_MINUTES, 10)
+            : 30,
+        maxSessions: process.env.MAX_SESSIONS
+            ? parseInt(process.env.MAX_SESSIONS, 10)
+            : 100,
+        fallbackEnabled: process.env.FALLBACK_ENABLED !== 'false',
     };
     const result = ConfigSchema.safeParse(raw);
     if (!result.success) {

package/dist/config.js.map

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

package/dist/deepseek-client.d.ts

@@ -1,11 +1,21 @@
 /**
  * DeepSeek API Client
  * Wrapper around OpenAI SDK for DeepSeek API
+ * Features: circuit breaker protection, automatic model fallback
  */
-import type { ChatCompletionParams, ChatCompletionResponse } from './types.js';
+import type { ChatCompletionParams, ChatCompletionResponse, FallbackInfo } from './types.js';
+/** Extended response with optional fallback info */
+export interface ChatCompletionResponseWithFallback extends ChatCompletionResponse {
+    fallback?: FallbackInfo;
+}
 export declare class DeepSeekClient {
     private client;
+    private circuitBreaker;
     constructor();
+    /**
+     * Get circuit breaker status
+     */
+    getCircuitBreakerStatus(): import("./types.js").CircuitBreakerStatus;
     /**
      * Build request params shared between streaming and non-streaming
      */
@@ -15,14 +25,22 @@ export declare class DeepSeekClient {
      */
     private wrapError;
     /**
-     * Create a chat completion (non-streaming)
+     * Parse raw API response into ChatCompletionResponse
      */
-    createChatCompletion(params: ChatCompletionParams): Promise<ChatCompletionResponse>;
+    private parseResponse;
     /**
-     * Create a streaming chat completion
+     * Create a chat completion (non-streaming) with circuit breaker and fallback
+     */
+    createChatCompletion(params: ChatCompletionParams): Promise<ChatCompletionResponseWithFallback>;
+    /**
+     * Create a streaming chat completion with circuit breaker and fallback
      * Returns the full text after streaming completes (buffered)
      */
-    createStreamingChatCompletion(params: ChatCompletionParams): Promise<ChatCompletionResponse>;
+    createStreamingChatCompletion(params: ChatCompletionParams): Promise<ChatCompletionResponseWithFallback>;
+    /**
+     * Internal streaming implementation
+     */
+    private streamInternal;
     /**
      * Test API connection
      */

package/dist/deepseek-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepseek-client.d.ts","sourceRoot":"","sources":["../src/deepseek-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EAKvB,MAAM,YAAY,CAAC;AAWpB,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;;IAavB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyD1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAOjB;;OAEG;IACG,oBAAoB,CACxB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,sBAAsB,CAAC;IA+ClC;;;OAGG;IACG,6BAA6B,CACjC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,sBAAsB,CAAC;IA0GlC;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAazC"}
+{"version":3,"file":"deepseek-client.d.ts","sourceRoot":"","sources":["../src/deepseek-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAUH,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EAItB,YAAY,EAEb,MAAM,YAAY,CAAC;AAiBpB,oDAAoD;AACpD,MAAM,WAAW,kCAAmC,SAAQ,sBAAsB;IAChF,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAwBD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAiB;;IAevC;;OAEG;IACH,uBAAuB;IAIvB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAyD1B;;OAEG;IACH,OAAO,CAAC,SAAS;IASjB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoCrB;;OAEG;IACG,oBAAoB,CACxB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,kCAAkC,CAAC;IAoD9C;;;OAGG;IACG,6BAA6B,CACjC,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,kCAAkC,CAAC;IAwC9C;;OAEG;YACW,cAAc;IA4F5B;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;CAazC"}