output-parsers
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.
When & Why to Use This Skill
This Claude skill automates the generation of structured output parsers for Python tools within the mcptools ecosystem. It enables developers to transform unstructured raw strings or simple result models into validated, schema-backed ParseResult objects, significantly improving data reliability and interoperability for AI agents and automated workflows.
Use Cases
- Converting raw JSONL or XML strings from web search and scraping tools into structured Pydantic models for easier data manipulation.
- Standardizing unstructured text outputs from legacy CLI tools into consistent, machine-readable formats.
- Enhancing tool reliability by implementing dedicated parser modules with custom error handling and validation logic.
- Streamlining the development of new Model Context Protocol (MCP) tools by providing a systematic workflow for output structuring and testing.
| 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
strdirectly - A
Resultmodel with a singlestrfield (namedresult,content,output, etc.) plus onlymodel_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
Paramsclass 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:
- A
ParseResultmodel:
class ParseResult(BaseModel):
"""Parsed result containing structured data."""
model_config = ConfigDict(
use_enum_values=True,
)
<field_name>: <field_type> = Field(..., title="<Title>")
- 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:
SearchResultmodel for individual itemsParseResultwithresults: 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:
Articlemodel for individual itemsParseResultwitharticles: list[Article]run_parsed()that parsesresult.resultinto structured objects