Skip to content

Conversation

jasminepoon
Copy link

Motivation and Context

Background / Problem

  • Allow users to create a Block that carries whatever structure they need (a vault pointer, a sticker, a math formula, etc.) and drop it into an MCP Conversation or Message.
  • At the moment the SDK recognises only the (future) built-in Block kinds hard-coded in core modules.
  • Anyone who invents a new Block—say context_pointer, sticker, or math_formula—must fork the repo or monkey-patch import logic. That fragments the ecosystem and creates maintenance overhead.

Ideal State:

  • register_block("my-kind") lets you map the string "my-kind" to a Python class that knows how to hold / validate / (de)serialize your custom data.
  • When the SDK later sees {"kind": "my-kind", ...} in JSON, it looks up the class in the registry instead of complaining “unknown kind”.

Goal

Add a tiny, stable API that lets external libraries register additional Block kinds at import-time, without touching MCP’s wire format or expanding the core code-base every time a new idea appears.

TLDR

Adds a lightweight Block registry so external packages can declare new kind strings without modifying the core SDK.

Key API:
from mcp.blocks.registry import register_block, get_block_class
@register_block("my-kind")
class MyBlock(Block): ...

  • new file src/mcp/blocks/registry.py (~79 logical LOC)
  • helpers list_block_kinds(), is_block_kind_registered() and UnknownBlockKindError
  • duplicate registrations ⇒ RuntimeWarning, last one wins
  • unit-tests tests/test_registry.py (5 cases)
  • README section “Custom blocks” with runnable example

No built-in Blocks exist today, so no other code files needed to be modified.

How Has This Been Tested?

  • Pytest suite passes (196 tests, 1 skipped)
  • Test coverage matches described scenarios

Breaking Changes

  • n/a

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

  • Diff size: ≈210 physical lines added, of which ~79 are executable code.
  • Future core Blocks can self-register by adding the decorator.

· Scope

✔ Add src/mcp/blocks/registry.py
• register_block(kind) decorator
• get_block_class(kind) lookup
• list_block_kinds() / is_block_kind_registered() helpers
• UnknownBlockKindError for clearer exceptions
✔ Emit RuntimeWarning on duplicate registration (non-fatal, last one wins)
✔ Ship unit-tests (five cases)
✔ Add README snippet under “Custom blocks” showing basic usage
✘ No deserializer changes (none in repo yet)
✘ No spec or wire-format edits

· Design Notes

  • Registry is a plain in-memory dict[str, type[Block]]; no new deps.
  • Thread-safety: CPython dict ops are atomic; docstring calls this out.
  • Duplicate-kind policy kept lenient for backward compatibility; can be tightened later (strict=True) if desired.
  • Overhead: one dictionary lookup per block; minimal.

@jasminepoon
Copy link
Author

can't add reviewers directly as per guidelines, tagging for visibility @jerome3o-anthropic @jspahrsummers -- pls review thanks!

@ihrpr
Copy link
Contributor

ihrpr commented May 23, 2025

Thank you for this contribution. However, this PR introduces infrastructure for "Blocks" - a concept that doesn't
currently exist in the MCP protocol. This creates maintenance burden without providing usable value.

@ihrpr ihrpr closed this May 23, 2025
gspencergoog pushed a commit to gspencergoog/mcp-python-sdk that referenced this pull request Jul 29, 2025
…lyhim/docs-small-fix-to-contributing-doc

docs: small fix to contributing doc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants