Request: Follow MCP specification for backward compatibility with structured content

[gwtaylor]

Hi @admk! First, thank you for creating sembr and making it accessible via MCP Server - this is a very useful tool for applying semantic line breaks programmatically.

Issue Description

I've been testing the MCP server integration with both Zed Editor and Claude Desktop, and I've discovered that neither client currently supports the structured_content field introduced in the MCP spec version 6/18/2025. Both clients only display the content field, which means clients only see the summary message ("Performed semantic line breaks to N lines") rather than the actual wrapped text.

Current Behaviour

The tool correctly returns both fields as per the FastMCP specification:

• content: Contains the human-readable summary
• structured_content: Contains the actual wrapped text in the output field

However, since most MCP clients haven't yet implemented support for structured_content, the wrapped text remains inaccessible to users.

Proposed Solution

According to the MCP specification, tools that return structured content should follow this guidance:

"For backwards compatibility, a tool that returns structured content SHOULD also return functionally equivalent unstructured content. (For example, serialized JSON can be returned in a TextContent block.)"

Could you update the tool to include the wrapped text in the content field alongside the summary? This would make it compliant with the MCP specification's backward compatibility recommendation.

For example:

# Current code:
return ToolResult(
    content=[TextContent(type="text", text=readable)],
    structured_content={"success": True, "output": wrapped_text})

# Suggested change:
return ToolResult(
    content=[TextContent(type="text", text=f"{readable}\n\n{wrapped_text}")],
    structured_content={"success": True, "output": wrapped_text})

This simply appends the wrapped text to the existing readable summary, ensuring backward compatibility without losing any existing functionality.

Context

This appears to be a widespread compatibility issue affecting various MCP integrations. The research I found indicates that:

• Claude Desktop currently ignores structured_content entirely
• Zed Editor's MCP integration doesn't parse structured content
• Other tools like langchain-mcp-adapters face similar limitations

Alternative Approaches

I originally thought of applying a command-line flag for legacy support, like --legacy-client-support or --include-output-in-content that would modify the tool's behaviour to include the wrapped text directly in the content field alongside the summary message.

However, since reading the MCP spec, I think the better solution is to follow the official MCP backward compatibility guidelines. This would ensure it works with both legacy and modern MCP clients.

Thanks again for this excellent tool!

[admk]

Hi @gwtaylor,

Thanks for this detailed issue and for using SemBr with MCP! You've identified a real compatibility problem with current MCP clients.

I think your suggestion to follow the MCP specification's backward compatibility guidelines is the right approach. I'm planning to modify the MCP implementation to include the structured content as serialized JSON in the content field, which should make it work with both legacy and modern MCP clients.

Here's what I'm thinking:

import json

# ... existing code ...

structured_data = {"success": True, "output": wrapped_text, "file_type": file_type}
return ToolResult(
    content=[TextContent(type="text", text=json.dumps(structured_data, indent=2))],
    structured_content=structured_data)

This change would:

1. Make the tool compliant with the MCP specification's backward compatibility recommendation
2. Ensure the wrapped text is accessible to clients that don't yet support structured_content
3. Maintain forward compatibility with clients that do support structured_content

What do you think of this approach? Would this solve the issue you're experiencing with Zed Editor and Claude Desktop?

[gwtaylor]

Hi @admk,
Thanks for responding so quickly! Your proposed solution sounds good to me.
I see that you have a commit on the fix/mcp branch. I am happy to test it with my Claude Desktop & Zed Editor setups.
Do you prefer I clone that branch and report back here, or would you like to open a PR and I can do more formal code review?

[admk]

Please go ahead and test with your Claude Desktop & Zed Editor setups, and let me know how it works with your setups! If everything looks good, I'll merge this into main.

[gwtaylor]

I've been testing the fix/mcp branch to validate the MCP server functionality, but I'm encountering a module import error that prevents sembr from working properly.

Testing Results

Claude Desktop Integration

When I configured Claude Desktop to use the fix/mcp branch:

"sembr": {
  "type": "stdio",
  "command": "uvx",
  "args": ["--from", "git+https://github.com/admk/sembr@fix/mcp", "sembr", "--mcp"]
}

I receive this error when trying to use the sembr tool:

Error processing text: No module named 'sembr.processors'

Command Line Testing

I also tested this from the command line and can reproduce the same issue. Here are the exact commands and outputs:

Working with PyPI version:

$ pbpaste | uvx --refresh sembr

Installed 85 packages in 333ms
100%|███████████████| 1/1 [00:00<00:00, 10.10it/s]
Bayfield is a small, historic village on Lake Huron,
set along Highway 21
between Goderich and Grand Bend.
Its heritage Main Street
has boutiques and inns,
while the sandy beach, marina at the Bayfield River,
and bluff-top Pioneer Park
make it a favourite for sunsets and relaxed, walkable getaways.

Broken with fix/mcp branch:

$ pbpaste | uvx --refresh --from git+https://github.com/admk/sembr@fix/mcp sembr

Installed 93 packages in 415ms
Traceback (most recent call last):
  File "/Users/gwtaylor/.cache/uv/archive-v0/3cwlNMaOO7VCDE2b2Hb6i/bin/sembr", line 12, in <module>
    sys.exit(main())
  File "/Users/gwtaylor/.cache/uv/archive-v0/3cwlNMaOO7VCDE2b2Hb6i/lib/python3.10/site-packages/sembr/cli.py", line 234, in main
    tokenizer, model, processor = init(
  File "/Users/gwtaylor/.cache/uv/archive-v0/3cwlNMaOO7VCDE2b2Hb6i/lib/python3.10/site-packages/sembr/cli.py", line 52, in init
    from .processors import get_processor
ModuleNotFoundError: No module named 'sembr.processors'

I note that the PyPi version only installs 85 packages while the fix/mcp version installs 93 packages.
Also, this issue may be unrelated to this particular MCP issue / fix. It could be anything that happened between the PyPi deployment and the fe0aef3 commit.

Thanks again for your help!