feat(mcp): add MCP JSON renderer and CLI support, update tests accordingly
- Add MCPRenderer to generate MCP-native JSON bundles (index.json, nav.json, modules/*.json) - Expose MCPRenderer via public API and CLI (`generate-mcp` command) - Replace Markdown-based MCP output with structured JSON resources - Update MCP renderer type stubs to match new JSON-based implementation - Refactor MCP tests to validate JSON content, bundle structure, and navigation - Fix MCP module coverage test to use explicit project_root for reliable discovery
This commit is contained in:
@@ -1,78 +1,102 @@
|
||||
import json
|
||||
from pathlib import Path
|
||||
from typing import Iterable
|
||||
from typing import Dict, List
|
||||
|
||||
from docforge.models import Project, Module, DocObject
|
||||
|
||||
|
||||
class MCPRenderer:
|
||||
"""
|
||||
Renderer that emits documentation as MCP resources.
|
||||
Renderer that emits MCP-native JSON resources from docforge models.
|
||||
"""
|
||||
|
||||
name = "mcp"
|
||||
|
||||
def generate_sources(self, project: Project, out_dir: Path) -> None:
|
||||
"""
|
||||
Generate MCP-compatible resources for the project.
|
||||
|
||||
Each module is rendered as a standalone MCP document.
|
||||
Generate MCP-compatible JSON resources and navigation for the project.
|
||||
"""
|
||||
out_dir.mkdir(parents=True, exist_ok=True)
|
||||
modules_dir = out_dir / "modules"
|
||||
modules_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
nav: List[Dict[str, str]] = []
|
||||
|
||||
for module in project.get_all_modules():
|
||||
self._write_module(module, out_dir)
|
||||
self._write_module(module, modules_dir)
|
||||
|
||||
def _write_module(self, module: Module, out_dir: Path) -> None:
|
||||
nav.append({
|
||||
"module": module.path,
|
||||
"resource": f"mcp://modules/{module.path}",
|
||||
})
|
||||
|
||||
# Write nav.json
|
||||
(out_dir / "nav.json").write_text(
|
||||
self._json(nav),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
# Write index.json
|
||||
index = {
|
||||
"project": project.name,
|
||||
"type": "docforge-model",
|
||||
"modules_count": len(nav),
|
||||
"source": "docforge",
|
||||
}
|
||||
|
||||
(out_dir / "index.json").write_text(
|
||||
self._json(index),
|
||||
encoding="utf-8",
|
||||
)
|
||||
|
||||
def _write_module(self, module: Module, modules_dir: Path) -> None:
|
||||
"""
|
||||
Render a module and all contained objects.
|
||||
Serialize a module into an MCP JSON resource.
|
||||
"""
|
||||
resource_path = self._module_resource_path(module)
|
||||
content = self._render_module(module)
|
||||
payload = {
|
||||
"module": module.path,
|
||||
"content": self._render_module(module),
|
||||
}
|
||||
|
||||
file_path = out_dir / resource_path
|
||||
file_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
file_path.write_text(content, encoding="utf-8")
|
||||
out = modules_dir / f"{module.path}.json"
|
||||
out.parent.mkdir(parents=True, exist_ok=True)
|
||||
out.write_text(self._json(payload), encoding="utf-8")
|
||||
|
||||
def _render_module(self, module: Module) -> str:
|
||||
def _render_module(self, module: Module) -> Dict:
|
||||
"""
|
||||
Render a module into MCP-friendly Markdown.
|
||||
Render a Module into MCP-friendly structured data.
|
||||
"""
|
||||
lines: list[str] = []
|
||||
|
||||
lines.append(f"# Module `{module.path}`\n")
|
||||
|
||||
if module.docstring:
|
||||
lines.append(module.docstring.strip() + "\n")
|
||||
data: Dict = {
|
||||
"path": module.path,
|
||||
"docstring": module.docstring,
|
||||
"objects": {},
|
||||
}
|
||||
|
||||
for obj in module.get_all_objects():
|
||||
lines.extend(self._render_object(obj, level=2))
|
||||
data["objects"][obj.name] = self._render_object(obj)
|
||||
|
||||
return "\n".join(lines).strip() + "\n"
|
||||
return data
|
||||
|
||||
def _render_object(self, obj: DocObject, level: int) -> Iterable[str]:
|
||||
def _render_object(self, obj: DocObject) -> Dict:
|
||||
"""
|
||||
Recursively render DocObjects.
|
||||
Recursively render a DocObject into structured MCP data.
|
||||
"""
|
||||
prefix = "#" * level
|
||||
lines: list[str] = []
|
||||
data: Dict = {
|
||||
"name": obj.name,
|
||||
"kind": obj.kind,
|
||||
"path": obj.path,
|
||||
"signature": obj.signature,
|
||||
"docstring": obj.docstring,
|
||||
}
|
||||
|
||||
lines.append(f"{prefix} {obj.kind} `{obj.name}`")
|
||||
members = list(obj.get_all_members())
|
||||
if members:
|
||||
data["members"] = {
|
||||
member.name: self._render_object(member)
|
||||
for member in members
|
||||
}
|
||||
|
||||
if obj.signature:
|
||||
lines.append(f"```python\n{obj.signature}\n```")
|
||||
return data
|
||||
|
||||
if obj.docstring:
|
||||
lines.append(obj.docstring.strip())
|
||||
|
||||
for member in obj.get_all_members():
|
||||
lines.extend(self._render_object(member, level + 1))
|
||||
|
||||
return lines
|
||||
|
||||
def _module_resource_path(self, module: Module) -> Path:
|
||||
"""
|
||||
Convert a module path into an MCP resource path.
|
||||
Example:
|
||||
docforge.models.module -> docforge/models/module.md
|
||||
"""
|
||||
return Path(module.path.replace(".", "/") + ".md")
|
||||
@staticmethod
|
||||
def _json(data: Dict) -> str:
|
||||
return json.dumps(data, indent=2, ensure_ascii=False)
|
||||
|
||||
@@ -1,31 +1,26 @@
|
||||
from pathlib import Path
|
||||
from typing import Iterable
|
||||
from typing import Dict, List
|
||||
|
||||
from docforge.models import Project, Module, DocObject
|
||||
|
||||
|
||||
class MCPRenderer:
|
||||
"""
|
||||
Renderer that emits MCP-compatible documentation resources.
|
||||
"""
|
||||
"""Renderer that emits MCP-native JSON resources from docforge models."""
|
||||
|
||||
name: str
|
||||
|
||||
def generate_sources(self, project: Project, out_dir: Path) -> None:
|
||||
"""Generate MCP resources for the given project."""
|
||||
"""Generate MCP-compatible JSON resources and navigation for the project."""
|
||||
|
||||
def _write_module(self, module: Module, out_dir: Path) -> None:
|
||||
"""Write a single module as an MCP resource."""
|
||||
def _write_module(self, module: Module, modules_dir: Path) -> None:
|
||||
"""Serialize a module into an MCP JSON resource."""
|
||||
|
||||
def _render_module(self, module: Module) -> str:
|
||||
"""Render a module and its contents into a text document."""
|
||||
def _render_module(self, module: Module) -> Dict:
|
||||
"""Render a Module into MCP-friendly structured data."""
|
||||
|
||||
def _render_object(
|
||||
self,
|
||||
obj: DocObject,
|
||||
level: int,
|
||||
) -> Iterable[str]:
|
||||
"""Recursively render a documented object and its members."""
|
||||
def _render_object(self, obj: DocObject) -> Dict:
|
||||
"""Recursively render a DocObject into structured MCP data."""
|
||||
|
||||
def _module_resource_path(self, module: Module) -> Path:
|
||||
"""Compute the MCP resource path for a module."""
|
||||
@staticmethod
|
||||
def _json(data: Dict) -> str:
|
||||
"""Serialize structured data to formatted JSON."""
|
||||
|
||||
Reference in New Issue
Block a user