output-parsers

gradion-ai 的头像作者 gradion-ai

为具有非结构化返回类型的 mcptools 生成输出解析器。当工具返回原始字符串或具有单个 str 字段的结果模型并且需要结构化 ParseResult 输出时使用。涵盖测试工具、识别可解析结构、使用 ParseResult 模型扩展模块以及创建解析器实现。

📖 中文导读:为具有非结构化返回类型的 mcptools 生成输出解析器。当工具返回原始字符串或具有单个 str 字段的结果模型并且需要结构化 ParseResult 输出时使用。涵盖测试工具、识别可解析结构、使用 ParseResult 模型扩展模块以及创建解析器实现。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: output-parsers description: Generate output parsers for mcptools with unstructured return types. Use when a tool returns raw strings or Result models with single str fields and needs structured ParseResult output. Covers testing tools, identifying parseable structures, extending modules with ParseResult models, and creating parser implementations.

Output Parsers for mcptools

Generate output parsers for Python tools in the mcptools package that have unstructured return types.

Identifying Unstructured Return Types

A tool has an unstructured return type when its run() function returns:

  • A str directly
  • A Result model with a single str field (named result, content, output, etc.) plus only model_config

A Result model with multiple fields (beyond model_config) has a structured return type and does not need a parser.

Workflow

1. Test the Python tool

Run the Python tool with ipybox_execute_ipython_cell tool using 2-3 example inputs to observe return value patterns:

from mcptools.<category>.<tool> import run, Params

result = run(Params(...))
print(result)  # or print(result.result) for Result types

2. Identify structure

Examine the output for parseable structure (JSON, JSONL, XML, delimited text, etc.). If no consistent structure exists, a parser cannot be generated.

3. Extend the Python tool module

Preservation rules when extending tool modules:

  • Never modify existing Params class or other existing model definitions
  • Never remove or modify existing imports (they may be used by existing code)
  • Only add new imports, models, and functions

Add to mcptools/<category>/<tool>.py:

  1. A ParseResult model:
class ParseResult(BaseModel):
    """Parsed result containing structured data."""

    model_config = ConfigDict(
        use_enum_values=True,
    )
    <field_name>: <field_type> = Field(..., title="<Title>")
  1. A run_parsed() function:
def run_parsed(params: Params) -> ParseResult:
    """Run tool and return parsed structured data.

    Args:
        params: Tool parameters

    Returns:
        ParseResult with structured data
    """
    from mcpparse.<category>.<tool> import parse

    result = run(params)
    # For str return: return parse(result)
    # For Result return: return parse(result.result)
    return parse(result)

4. Create parser module

Create mcpparse/<category>/<tool>.py with:

from mcptools.<category>.<tool> import ParseResult


class <Tool>ParseError(Exception):
    """Exception raised when parsing <tool> results fails."""
    pass


def parse(result: str) -> ParseResult:
    """Parse <tool> result into structured data.

    Args:
        result: Raw string result from the tool

    Returns:
        ParseResult with structured data

    Raises:
        <Tool>ParseError: If parsing fails
    """
    # Implementation based on observed output structure
    ...
    return ParseResult(...)

5. Test run_parsed()

Call the ipybox_reset tool to restart the IPython kernel so the next import loads the modified module.

Then test with ipybox_execute_ipython_cell using the same example inputs from step 1:

from mcptools.<category>.<tool> import run_parsed, Params

result = run_parsed(Params(...))
print(result)

Verify that the ParseResult fields are correctly populated.

Examples

str return type (brave_web_search)

Original: run(params: Params) -> str returns JSONL

Extended with:

  • SearchResult model for individual items
  • ParseResult with results: list[SearchResult]
  • run_parsed() that parses JSONL into structured objects

Result return type (search_abstracts)

Original: run(params: Params) -> Result where Result.result: str

Extended with:

  • Article model for individual items
  • ParseResult with articles: list[Article]
  • run_parsed() that parses result.result into structured objects