code_docstring

Instructions

Implementation Reference

• src/onion_mcp_server/tools/code.py:106-175 (handler)

  The handle_code async function dispatches all code tools. For 'code_docstring' (lines 161-169), it generates a prompt asking an LLM to produce docstrings for the given code in the specified style (google, numpy, sphinx, jsdoc) and language, then calls llm_call to execute it.

  async def handle_code(name: str, arguments: dict) -> list[types.TextContent]:
      a = arguments
  
      if name == "code_explain":
          detail_map = {"brief": "用一两句话简短", "detailed": "非常详细地", "normal": ""}
          detail_str = detail_map.get(a.get("detail", "normal"), "")
          lang       = a.get("language", "") or "（自动检测）"
          prompt = (
              f"请{detail_str}解释以下 {lang} 代码的功能和逻辑，"
              f"包括：整体作用、关键步骤、重要变量/函数的含义。\n\n"
              f"```\n{a['code']}\n```"
          )
  
      elif name == "code_review":
          focus     = a.get("focus", ["all"])
          focus_str = "所有方面（Bug、安全、性能、代码风格）" if "all" in focus else "、".join(focus)
          lang      = a.get("language", "") or ""
          prompt = (
              f"请对以下 {lang} 代码进行代码审查，重点关注：{focus_str}。\n"
              f"请按以下格式输出：\n"
              f"1. 问题列表（严重程度 + 描述 + 修复建议）\n"
              f"2. 整体评分（1-10）\n"
              f"3. 改进后的代码（如有必要）\n\n"
              f"```\n{a['code']}\n```"
          )
  
      elif name == "code_generate":
          style_map = {
              "simple":     "简洁易读",
              "production": "生产级别（含完整错误处理、日志、类型注解）",
          }
          style_str = style_map.get(a.get("style", "simple"), "简洁易读")
          lang      = a.get("language", "Python")
          prompt = (
              f"请用 {lang} 编写以下功能的代码，风格要求：{style_str}。\n"
              f"只输出代码和必要的注释，不需要额外解释。\n\n"
              f"需求：{a['description']}"
          )
  
      elif name == "code_convert":
          prompt = (
              f"请将以下 {a['from_language']} 代码转换为 {a['to_language']}。\n"
              f"要求：保持逻辑完全一致，使用目标语言的惯用写法，只输出转换后的代码。\n\n"
              f"```{a['from_language'].lower()}\n{a['code']}\n```"
          )
  
      elif name == "code_fix":
          err_part = f"\n\n错误信息：\n```\n{a['error_message']}\n```" if a.get("error_message") else ""
          lang     = a.get("language", "") or ""
          prompt = (
              f"请修复以下 {lang} 代码中的错误。\n"
              f"要求：输出修复后的完整代码，并在代码前简要说明修复了什么问题。\n\n"
              f"```\n{a['code']}\n```{err_part}"
          )
  
      elif name == "code_docstring":
          style    = a.get("style", "google")
          language = a.get("language", "Python")
          prompt = (
              f"请为以下 {language} 代码生成 {style} 风格的文档注释（docstring）。\n"
              f"要求：为每个函数/类/方法添加完整的参数说明、返回值说明、异常说明（如有）。\n"
              f"只输出添加了文档注释的完整代码。\n\n"
              f"```\n{a['code']}\n```"
          )
  
      else:
          raise ValueError(f"未知 code 工具: {name}")
  
      reply = await llm_call(prompt)
      return [types.TextContent(type="text", text=reply)]

• src/onion_mcp_server/tools/code.py:86-102 (schema)

  Defines the 'code_docstring' tool registration with its name, description, and inputSchema. Accepts 'code' (string, required), 'language' (string, default Python), and 'style' (enum: google/numpy/sphinx/jsdoc, default google).

  types.Tool(
      name="code_docstring",
      description="为函数、类或模块生成文档注释（docstring）。",
      inputSchema={
          "type": "object",
          "properties": {
              "code":     {"type": "string"},
              "language": {"type": "string", "default": "Python"},
              "style":    {
                  "type": "string",
                  "enum": ["google", "numpy", "sphinx", "jsdoc"],
                  "default": "google",
              },
          },
          "required": ["code"],
      },
  ),

• src/onion_mcp_server/server.py:22-22 (registration)

  CODE_TOOLS and handle_code are imported from the code module into the server.

  from onion_mcp_server.tools.code   import CODE_TOOLS,   handle_code

• src/onion_mcp_server/server.py:52-53 (registration)

  Each code tool (including 'code_docstring') is registered in the _HANDLERS routing table, mapping its name to handle_code.

  for _t in CODE_TOOLS:   
      _HANDLERS[_t.name] = handle_code

• src/onion_mcp_server/tools/_llm.py:78-88 (helper)

  llm_call is the helper invoked by handle_code to send the generated prompt to the configured LLM and return the docstring result.

  async def llm_call(
      prompt: str,
      system: Optional[str] = None,
      temperature: float = 0.7,
  ) -> str:
      """单轮调用"""
      messages = []
      if system:
          messages.append({"role": "system", "content": system})
      messages.append({"role": "user", "content": prompt})
      return await llm_chat(messages, temperature=temperature)