Fix warning with drf-spectacular

[roskakori]

When adding django-mcp-server to a project that uses drf-spectacular to generate an OpenAPI specification for the endpoints provided by DRF, the following fails:

python manage.py spectacular --validate --fail-on-warn --file /tmp/some.yaml

With the error message:

.../mcp_server/views.py:13: Error [MCPServerStreamableHttpView]: unable to guess serializer. This is graceful fallback handling for APIViews. Consider using GenericAPIView as view base class, if view is under your control. Either way you may want to add a serializer_class (or method). Ignoring view for now.

Workaround

1. Remove the command line option --fail-on-warn. However, this is not ideal because then other warnings also slip through.
2. Remove the MCP server endpoint from the OpenAPI specification using a precprocessing hook. This seems fine enough because few will call the MCP server directly by using its REST endpoint.

The latter can be done with:

# settings.py
SPECTACULAR_SETTINGS = {
    ...
    "PREPROCESSING_HOOKS": ["core.mcp.endpoints_without_mcp_server"],
    ...
}

# core/mcp.py
def endpoints_without_mcp_server(endpoints: list[tuple]) -> list[tuple]:
    """
    Preprocessing hook for drf-spectacular that excludes mcp-server endpoints.
    """
    return [
        (path, path_regex, method, callback) 
        for path, path_regex, method, callback in endpoints 
        if path != "/mcp"
    ]

Permanent solution

While this workaround works for me, basically everybody else using drf-spectacular would need to add it to their project, too. So I was wondering if a general solution could be added.

As far as I understand, all the MCP server endpoints just use JSON RPC 2.0. So basically adding a serializer that represents JSON 2.0 to the endpoints in MCPServerStreamableHttpView should do the trick. Something along the line:

from rest_framework import serializers

class JsonRpcSerializer(serializers.Serializer):
    id = serializers.IntegerField()
    jsonrpc = serializers.CharField(read_only=True)
    method = serializers.CharField()
    params = serializers.ListField(child=serializers.DictField(), required=False)
    error = serializers.DictField(required=False)

If you are interested, I can make a stab at it.

But maybe there is a better solution, so I'm putting this up for discussion first.

PS: Thank you for this library, in particular for the remarkably elegant and clean design that integrates so well with DRF.

[omarbenhamid]

Currently we use the raw request to pass it to FastMCP server, so we do not need a serializer.

Could you try using @extend_schema(exclude=True) on the MCPServerStreamableHttpView or get/post and delete methods.

If it solves the problème please send a PR and I will merge it.

[roskakori]

@omarbenhamid I am happy to report that @extend_schema(exclude=True) works just fine. See PR #42.

However, django-mcp-server now has a dependency on drf-spectacular. My initial proposal with adding a serializer would have worked without that and only required django-rest-framework.

If you are fine with that, feel free to merge. If you want me to look into the serializer, let me know and I rework the PR.

[omarbenhamid]

You're right, the exclude_schema does add this undesired dependency.
On the other hand this serializer is not technically needed and it creates coupling with JSONRPC and MCP Specs : it will need to be maintained if in the future one of this spec evolves. So i'm not confortable with introducting it just to avoid a warning for users of drf-spectacular.

We have two options :

1. Either document in the README how to setup the pre-processing hook to avoid this warning.
2. Have some guarded import (with try except) of extend_schema with a dummy implementation if it cannot be imported. Sth like :

   try:
       from drf_spectacular.utils import extend_schema
   except:
       extend_schema = lambda exclude: (lambda x: x)

Personally, for this third party framework specific issues that are just "WARNINGs" I would tend to just document it to avoid adding lines of code ...

[roskakori]

@omarbenhamid

On the other hand this serializer is not technically needed and it creates coupling with JSONRPC and MCP Specs : it will need to be maintained if in the future one of this spec evolves. So i'm not confortable with introducting it just to avoid a warning for users of drf-spectacular.

JSON-RPC 2.0 does not seem to evolve much (created in 2010, last updated in 2013), but who knows where MCP goes. So I can see your point.

1. Either document in the README how to setup the pre-processing hook to avoid this warning.

Yes, that would also be an approach: Just extending the README with my workaround. The only disadvantage is that now everyone who wants a clean drf-spectacular setup needs to apply it. Not sure how many even want that and don't care about warnings anyway. (I apparently do.) It only fails if you specify the --fail-on-warn command line option.

2. Have some guarded import (with try except) of extend_schema...

That looks only a little confusing, and has a nice out-of-the-box experience for users of drf-spectacular. In combination with a nice comment on why it is done that way, also pointing to this GitHub issue, it actually feels nice to me.

From a developer experience's point of view, personally I'd probably prefer 2., but 1. sounds reasonable to keep the code tight and clean.

Please let me know what you prefer and I make another PR.

[omarbenhamid]

From a developer experience's point of view, personally I'd probably prefer 2., but 1. sounds reasonable to keep the code tight and clean.

@roskakori I like it to with the guarded import, with the exclude_schema annotation. If you still have time to update the PR it would be merged in next release.