completion

Instructions

Implementation Reference

• src/mcp-server.ts:294-334 (registration)

  Tool registration for 'completion' using server.registerTool with description, inputSchema, and the async handler function (lines 294-334). Also listed in ENDPOINT_MATRIX at line 37.

  server.registerTool(
    "completion",
    {
      description:
        "DeepSeek V4 Pro FIM completion tool for prompt/suffix fill-in-the-middle workflows. Defaults to `deepseek-v4-pro`. Use this when you need raw completion text instead of chat message formatting. Set `include_raw_response=true` only when you need the full provider payload for debugging.",
      inputSchema: completionToolInputSchema,
    },
    async (input) => {
      try {
        const normalizedInput = input as CompletionToolInput;
        const request = buildCompletionRequest(normalizedInput, options.defaultModel);
        const result = await options.client.createCompletion(request);
        const choice = result.response.choices[0];
        const includeRawResponse = normalizedInput.include_raw_response;
  
        const structuredContent: Record<string, unknown> = {
          model: result.response.model,
          text: choice?.text ?? "",
          finish_reason: choice?.finish_reason ?? null,
          usage: result.response.usage ?? null,
          stream_chunk_count: result.streamChunkCount ?? null,
        };
  
        if (includeRawResponse) {
          structuredContent.raw_response = result.response;
        }
  
        return {
          content: [
            {
              type: "text",
              text: choice?.text || "(no completion text returned)",
            },
          ],
          structuredContent,
        };
      } catch (error) {
        return makeToolErrorResult(error);
      }
    },
  );

• src/deepseek/schemas.ts:107-122 (schema)

  Input schema for the 'completion' tool defined with Zod. Includes fields: model (default deepseek-v4-pro), prompt (required), suffix, max_tokens, temperature, top_p, stream, logprobs, echo, stop, presence_penalty, frequency_penalty, include_raw_response, extra_body.

  export const completionToolInputSchema = z.object({
    model: z.string().default("deepseek-v4-pro"),
    prompt: z.string().min(1),
    suffix: z.string().optional(),
    max_tokens: z.number().int().positive().optional(),
    temperature: z.number().min(0).max(2).optional(),
    top_p: z.number().min(0).max(1).optional(),
    stream: z.boolean().default(false),
    logprobs: z.number().int().min(0).max(20).optional(),
    echo: z.boolean().optional(),
    stop: stopSchema.optional(),
    presence_penalty: z.number().min(-2).max(2).optional(),
    frequency_penalty: z.number().min(-2).max(2).optional(),
    include_raw_response: z.boolean().default(false),
    extra_body: z.record(z.string(), z.unknown()).optional(),
  });

• src/mcp-server.ts:504-539 (helper)

  Helper function buildCompletionRequest that transforms the typed CompletionToolInput into a DeepSeekCompletionRequest, copying optional fields and extra_body.

  function buildCompletionRequest(
    input: CompletionToolInput,
    defaultModel: string,
  ): DeepSeekCompletionRequest {
    const request: DeepSeekCompletionRequest = {
      model: input.model ?? defaultModel,
      prompt: input.prompt,
    };
  
    const optionalFields: (keyof CompletionToolInput)[] = [
      "suffix",
      "max_tokens",
      "temperature",
      "top_p",
      "stream",
      "logprobs",
      "echo",
      "stop",
      "presence_penalty",
      "frequency_penalty",
    ];
    const requestRecord = request as Record<string, unknown>;
  
    for (const field of optionalFields) {
      const value = input[field];
      if (value !== undefined) {
        requestRecord[field] = value;
      }
    }
  
    if (input.extra_body) {
      Object.assign(request, input.extra_body);
    }
  
    return request;
  }

• src/deepseek/client.ts:104-127 (handler)

  The createCompletion method on DeepSeekApiClient that makes the actual API call to /beta/completions, supporting both streaming (aggregated via aggregateCompletionChunks) and non-streaming modes, returning a CompletionExecutionResult.

  async createCompletion(request: DeepSeekCompletionRequest): Promise<CompletionExecutionResult> {
    if (request.stream) {
      const chunks = await this.requestSseJson<unknown>({
        method: "POST",
        path: "/beta/completions",
        body: request as Record<string, unknown>,
        stream: true,
      });
  
      return {
        response: aggregateCompletionChunks(chunks, String(request.model)),
        streamChunkCount: chunks.length,
      };
    }
  
    const response = await this.requestJson<DeepSeekCompletionResponse>({
      method: "POST",
      path: "/beta/completions",
      body: request as Record<string, unknown>,
      stream: false,
    });
  
    return { response };
  }

• src/deepseek/types.ts:78-181 (helper)

  Type definitions for DeepSeekCompletionRequest (request shape), DeepSeekCompletionChoice, DeepSeekCompletionResponse, and CompletionExecutionResult used by the completion tool.

  export interface DeepSeekCompletionRequest {
    model: DeepSeekModelId;
    prompt: string;
    suffix?: string;
    max_tokens?: number;
    temperature?: number;
    top_p?: number;
    stream?: boolean;
    logprobs?: number;
    echo?: boolean;
    stop?: string | string[];
    presence_penalty?: number;
    frequency_penalty?: number;
    [key: string]: unknown;
  }
  
  export interface DeepSeekUsage {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
    prompt_cache_hit_tokens?: number;
    prompt_cache_miss_tokens?: number;
    completion_tokens_details?: {
      reasoning_tokens?: number;
      [key: string]: unknown;
    };
    [key: string]: unknown;
  }
  
  export interface DeepSeekChatCompletionChoice {
    index: number;
    message: {
      role: "assistant";
      content: string | null;
      reasoning_content?: string;
      tool_calls?: DeepSeekToolCall[];
    };
    finish_reason: string | null;
    logprobs?: unknown;
  }
  
  export interface DeepSeekChatCompletionResponse {
    id: string;
    object: string;
    created: number;
    model: string;
    choices: DeepSeekChatCompletionChoice[];
    usage?: DeepSeekUsage;
    system_fingerprint?: string;
    [key: string]: unknown;
  }
  
  export interface DeepSeekCompletionChoice {
    index: number;
    text: string;
    logprobs?: unknown;
    finish_reason: string | null;
  }
  
  export interface DeepSeekCompletionResponse {
    id: string;
    object: string;
    created: number;
    model: string;
    choices: DeepSeekCompletionChoice[];
    usage?: DeepSeekUsage;
    system_fingerprint?: string;
    [key: string]: unknown;
  }
  
  export interface DeepSeekModel {
    id: string;
    object: string;
    owned_by?: string;
    created?: number;
    [key: string]: unknown;
  }
  
  export interface DeepSeekListModelsResponse {
    object: string;
    data: DeepSeekModel[];
  }
  
  export interface DeepSeekBalanceInfo {
    currency: string;
    total_balance: string;
    granted_balance: string;
    topped_up_balance: string;
  }
  
  export interface DeepSeekUserBalanceResponse {
    is_available: boolean;
    balance_infos: DeepSeekBalanceInfo[];
  }
  
  export interface ChatCompletionExecutionResult {
    response: DeepSeekChatCompletionResponse;
    streamChunkCount?: number;
  }
  
  export interface CompletionExecutionResult {
    response: DeepSeekCompletionResponse;
    streamChunkCount?: number;
  }