"""MCP Protocol Compliance Tests.
These tests verify that the Laravel MCP Companion server correctly implements
the Model Context Protocol specification.
"""
import pytest
import re
from laravel_mcp_companion import create_mcp_server
@pytest.fixture
def mcp_server(temp_dir):
"""Create an MCP server instance for testing."""
return create_mcp_server("TestServer", temp_dir, "12.x")
@pytest.mark.protocol
class TestServerCapabilities:
"""Test that server capabilities are correctly advertised."""
def test_server_has_tools(self, mcp_server):
"""Server should advertise available tools."""
# FastMCP stores tools internally
assert hasattr(mcp_server, '_tool_manager')
tools = mcp_server._tool_manager._tools
assert len(tools) > 0, "Server should have at least one tool"
def test_server_has_resources(self, mcp_server):
"""Server should advertise available resources."""
assert hasattr(mcp_server, '_resource_manager')
# Check that resource templates are registered
templates = mcp_server._resource_manager._templates
assert len(templates) > 0, "Server should have resource templates"
def test_server_has_prompts(self, mcp_server):
"""Server should advertise available prompts."""
assert hasattr(mcp_server, '_prompt_manager')
prompts = mcp_server._prompt_manager._prompts
assert len(prompts) > 0, "Server should have at least one prompt"
@pytest.mark.protocol
class TestToolSchemas:
"""Test that all tools have valid JSON schemas."""
def test_all_tools_have_descriptions(self, mcp_server):
"""Every tool should have a description."""
tools = mcp_server._tool_manager._tools
for name, tool in tools.items():
assert tool.description, f"Tool '{name}' missing description"
def test_tool_parameters_are_valid(self, mcp_server):
"""Tool parameters should be valid JSON Schema."""
tools = mcp_server._tool_manager._tools
for name, tool in tools.items():
# FastMCP tools have parameters defined via function signatures
# The schema is generated automatically
if hasattr(tool, 'parameters') and tool.parameters:
schema = tool.parameters
# Basic JSON Schema validation
assert isinstance(schema, dict), f"Tool '{name}' parameters not a dict"
def test_required_tools_exist(self, mcp_server):
"""Required documentation tools should exist."""
tools = mcp_server._tool_manager._tools
required_tools = [
"list_laravel_docs",
"search_laravel_docs",
"read_laravel_doc_content",
"get_laravel_package_recommendations",
"verify_laravel_feature",
]
for tool_name in required_tools:
assert tool_name in tools, f"Required tool '{tool_name}' missing"
@pytest.mark.protocol
class TestResourceTemplates:
"""Test that resource templates are valid URI templates."""
def test_laravel_resource_template(self, mcp_server):
"""Laravel resource template should be valid."""
templates = mcp_server._resource_manager._templates
# Check that we have a laravel:// resource template
template_uris = [str(t.uri_template) for t in templates.values()]
assert any("laravel://" in uri for uri in template_uris), \
"Missing laravel:// resource template"
def test_external_resource_template(self, mcp_server):
"""External Laravel services resource template should be valid."""
templates = mcp_server._resource_manager._templates
template_uris = [str(t.uri_template) for t in templates.values()]
assert any("laravel-external://" in uri for uri in template_uris), \
"Missing laravel-external:// resource template"
def test_resource_templates_have_parameters(self, mcp_server):
"""Resource templates should define their parameters."""
templates = mcp_server._resource_manager._templates
for name, template in templates.items():
uri = str(template.uri_template)
# URI templates use {param} syntax
if "{" in uri:
# Should have at least one parameter
params = re.findall(r'\{(\w+)\}', uri)
assert len(params) > 0, f"Template '{name}' has braces but no params"
@pytest.mark.protocol
class TestErrorResponses:
"""Test that error responses follow MCP spec format."""
def test_invalid_package_returns_error(self, mcp_server):
"""Requesting invalid package should return proper error."""
from laravel_mcp_companion import get_laravel_package_info
result = get_laravel_package_info("nonexistent/package")
# Should return TOON-encoded error
assert "error" in result.lower() or "not found" in result.lower()
def test_empty_search_query_handled(self, mcp_server, temp_dir):
"""Empty search queries should be handled gracefully."""
from mcp_tools import search_laravel_docs_impl
result = search_laravel_docs_impl(temp_dir, "", None, False, None, runtime_version="12.x")
# Should return error or empty results, not crash
assert result is not None
@pytest.mark.protocol
class TestToolInvocationStructure:
"""Test that tool invocations return correct content structure."""
def test_package_recommendations_return_structured_data(self, mcp_server):
"""Package recommendations should return structured TOON data."""
from laravel_mcp_companion import get_laravel_package_recommendations
result = get_laravel_package_recommendations("authentication")
# Should contain package data in TOON format
assert result is not None
assert len(result) > 0
# TOON format indicators
assert ":" in result or "packages" in result.lower()
def test_package_info_return_structure(self, mcp_server):
"""Package info should return expected fields."""
from laravel_mcp_companion import get_laravel_package_info
result = get_laravel_package_info("laravel/sanctum")
assert result is not None
# Should contain key fields in TOON format
assert "sanctum" in result.lower()
def test_feature_map_returns_structured_data(self, mcp_server):
"""Feature lookup should return structured data."""
from laravel_mcp_companion import get_features_for_laravel_package
result = get_features_for_laravel_package("laravel/sanctum")
assert result is not None
assert "features" in result.lower() or ":" in result
@pytest.mark.protocol
class TestPromptStructure:
"""Test that prompts follow MCP specification."""
def test_prompts_have_names(self, mcp_server):
"""All prompts should have names."""
prompts = mcp_server._prompt_manager._prompts
for name, prompt in prompts.items():
assert name, "Prompt must have a name"
assert len(name) > 0, "Prompt name cannot be empty"
def test_prompts_return_strings(self, mcp_server):
"""Prompt functions should return strings."""
prompts = mcp_server._prompt_manager._prompts
for name, prompt in prompts.items():
# FastMCP prompts have a fn attribute
if hasattr(prompt, 'fn') and prompt.fn:
result = prompt.fn()
assert isinstance(result, str), f"Prompt '{name}' should return string"
assert len(result) > 0, f"Prompt '{name}' returned empty string"
@pytest.mark.protocol
class TestToolAnnotations:
"""Test that tools have correct MCP annotations."""
def test_readonly_tools_are_marked(self, mcp_server):
"""Read-only tools should have readOnlyHint annotation."""
tools = mcp_server._tool_manager._tools
readonly_tools = [
"list_laravel_docs",
"search_laravel_docs",
"read_laravel_doc_content",
"get_laravel_package_recommendations",
"verify_laravel_feature",
]
for tool_name in readonly_tools:
if tool_name in tools:
tool = tools[tool_name]
# Check annotations if present (Pydantic model with attributes)
if hasattr(tool, 'annotations') and tool.annotations:
assert tool.annotations.readOnlyHint is True, \
f"Tool '{tool_name}' should be marked read-only"
def test_update_tools_not_marked_readonly(self, mcp_server):
"""Update tools should not be marked as read-only."""
tools = mcp_server._tool_manager._tools
update_tools = ["update_laravel_docs", "update_external_laravel_docs"]
for tool_name in update_tools:
if tool_name in tools:
tool = tools[tool_name]
if hasattr(tool, 'annotations') and tool.annotations:
# readOnlyHint should be False for update tools
assert tool.annotations.readOnlyHint is False, \
f"Tool '{tool_name}' should not be marked read-only"
