Unified server architecture serving both MCP and REST API endpoints #148

akolotov · 2025-07-11T00:51:34Z

This PR addresses functionality requested in #108 and includes all the changes made under the epic sub-issues:

Summary by CodeRabbit

New Features
- Introduced a comprehensive, versioned REST API for blockchain data access, including endpoints for blocks, transactions, addresses, tokens, contracts, and more.
- Added an informational landing page and AI agent guide for seamless integration and usage.
- Provided detailed API documentation and usage examples.
- Enabled REST API mode via a new CLI flag (--rest) alongside existing server modes.
Bug Fixes
- Corrected minor documentation typos and clarified descriptions.
Documentation
- Expanded and reorganized documentation for API usage, testing, and agent integration.
- Added guidelines for REST API implementation, testing, and documentation standards.
- Updated setup, testing, and client integration instructions.
Tests
- Added extensive automated tests for REST API endpoints and server CLI behavior to ensure reliability.
Chores
- Improved documentation structure and code comments for maintainability.

…de (#147)

coderabbitai · 2025-07-11T00:51:41Z

Walkthrough

A comprehensive REST API layer was added to the project, including route handlers, parameter validation, error handling, static content caching, and integration with the CLI. Extensive documentation was introduced for the API, along with new testing modules covering both the API routes and server CLI behavior. Associated rules and guidelines were also documented.

Changes

Files/Paths	Change Summary
`blockscout_mcp_server/api/…`	New API sub-package: adds `dependencies.py` (mock context), `helpers.py` (param validation, error handling), `routes.py` (REST endpoints, static content caching, route registration).
`blockscout_mcp_server/templates/index.html`, `blockscout_mcp_server/llms.txt`	New static files: landing page HTML and AI agent guide text.
`blockscout_mcp_server/server.py`	Adds `--rest` CLI flag, integrates REST API route registration, updates server startup logic.
`tests/api/test_routes.py`, `tests/test_server.py`	New test modules: REST API route tests (with mocking, parameter/error checks) and server CLI behavior tests.
`.cursor/rules/…`	New/updated rules: REST API implementation/testing/documentation guidelines, static content caching, workflow updates.
`API.md`, `README.md`, `SPEC.md`, `TESTING.md`, `AGENTS.md`	Adds/updates documentation: API reference, usage instructions, operational modes, manual testing, project overview.
`pyproject.toml`	Syntax fix: adds trailing comma to dependencies list.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant FastMCP REST API
    participant Helpers/Validation
    participant Tool Layer
    participant MockCtx

    Client->>FastMCP REST API: HTTP request (e.g., /v1/get_block_info?chain=...)
    FastMCP REST API->>Helpers/Validation: extract_and_validate_params(request)
    Helpers/Validation-->>FastMCP REST API: params or error
    alt params valid
        FastMCP REST API->>MockCtx: get_mock_context()
        FastMCP REST API->>Tool Layer: call tool_func(ctx, **params)
        Tool Layer-->>FastMCP REST API: tool result
        FastMCP REST API-->>Client: JSON response (ToolResponse)
    else params invalid
        Helpers/Validation-->>FastMCP REST API: raise ValueError
        FastMCP REST API-->>Client: 400 JSON error response
    end

Possibly related PRs

Add REST API scaffolding #140: Introduces initial REST API scaffolding and CLI support, which is directly extended and completed by this PR.
Add REST API endpoints and helpers #142: Adds and documents the same REST API endpoints, helpers, and testing infrastructure, indicating a direct code-level relationship.
Implement static web endpoints #141: Implements and tests static endpoints (/, /health, /llms.txt), which are expanded upon in this PR with dynamic REST routes and full API integration.

Suggested labels

codex

✨ Finishing Touches

📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 2

🧹 Nitpick comments (12)

.cursor/rules/110-new-mcp-tool.mdc (1)

110-116: Avoid duplicating registration logic – favour a unified helper

The added steps instruct developers to create per-tool REST wrappers. This diverges from the unified‐registration approach preferred by @akolotov (see learning note).
Consider extending the existing register_unified_tool(...) helper (or similar) so MCP and REST exposure stay DRY, and revise the instructions accordingly.
blockscout_mcp_server/api/dependencies.py (1)
4-23: Provide a generic fallback for unimplemented Context methods

Many tools call ctx.warning, ctx.debug, etc. If any such call slips through, MockCtx will raise AttributeError. A lightweight safeguard:
 class MockCtx:
@@
     async def report_progress(self, *args, **kwargs) -> None:
         """Simulate the ``report_progress`` method of an MCP ``Context``."""
         pass
+
+    # Fallback for any other context methods used by tools
+    def __getattr__(self, _name):
+        async def _noop(*_args, **_kwargs):  # type: ignore[return-value]
+            pass
+        return _noop
This keeps REST routes resilient if new context calls appear.
blockscout_mcp_server/server.py (1)

49-69: Consider implementing unified tool registration in the future.

Based on retrieved learnings, you prefer a unified tool registration approach that eliminates separate registration points. While the current implementation works correctly, consider refactoring to a unified registration system like register_unified_tool(mcp, tool_function, endpoint, tool_function_rest) to reduce duplication and maintenance burden.

.cursor/rules/230-api-route-tests.mdc (1)

10-15: Add note about async-test hygiene

The guideline forgets to mention two recurring pitfalls we keep seeing in route tests:

Always decorate coroutine tests with @pytest.mark.asyncio.

Ensure every httpx.AsyncClient is async with … or explicitly aclose()-d to avoid unclosed-socket warnings.

Consider amending the bullet list.

blockscout_mcp_server/templates/index.html (1)

3-7: Missing SEO / social meta tags

Adding a <meta name="description"> and basic OpenGraph tags (og:title, og:description, og:url) will improve link previews when the landing page is shared and helps search engines index the REST API doc.
README.md (2)
98-110: Terminology drift between “HTTP Mode” sections

The heading says “HTTP Mode (MCP only)” but the paragraph below still calls it “HTTP Streamable mode”. Pick one term (preferably “HTTP mode”) and use it consistently to avoid reader confusion.
-To run the server in HTTP Streamable mode (stateless, JSON responses):
+To run the server in HTTP mode (stateless MCP over HTTP):
112-125: Flag that –rest implicitly forces JSON responses

Readers might assume --rest keeps streamable SSE responses enabled. In practice the ASGI layer switches to plain JSON. A short parenthetical remark would make this explicit and spare users a round-trip of debugging.
blockscout_mcp_server/llms.txt (1)

24-35: Expose /health and /v1/tools early

The quick-start section is excellent, but many agents probe /health first. Mentioning it right after the base URL (and perhaps adding a sample call) will make adoption even smoother.

TESTING.md (1)

96-118: Clarify host binding & port reuse

The Docker example binds to 0.0.0.0:8000 but the local example leaves the host default (127.0.0.1). For parity—and to avoid the “works in Docker but not in WSL” tickets we keep seeing—consider adding --http-host 0.0.0.0 to the local command or add a note explaining the difference.
blockscout_mcp_server/api/helpers.py (1)
11-13: Consider supporting additional boolean representations.

The current implementation handles common truthy values, but you might want to consider supporting "on" and "off" as these are also common in web forms and query parameters.
 def str_to_bool(val: str) -> bool:
     """Convert a string to a boolean value."""
-    return val.lower() in ("true", "1", "t", "yes")
+    return val.lower() in ("true", "1", "t", "yes", "on")
SPEC.md (1)
27-27: Consider simplifying the phrasing.

The static analysis tool suggests considering a shorter alternative to "in conjunction with".
-   - Enabled by using the `--rest` flag in conjunction with `--http`.
+   - Enabled by using the `--rest` flag together with `--http`.
blockscout_mcp_server/api/routes.py (1)

242-258: Consider implementing unified tool registration in the future.

Based on previous discussions, a unified registration approach (e.g., register_unified_tool(mcp, tool_function, endpoint, tool_function_rest)) could reduce maintenance burden by eliminating dual registration points between this file and server.py.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 02dc7e0 and b078bea.

📒 Files selected for processing (21)

.cursor/AGENTS.md (1 hunks)
.cursor/rules/110-new-mcp-tool.mdc (1 hunks)
.cursor/rules/150-rest-api-implementation.mdc (1 hunks)
.cursor/rules/160-static-content-caching.mdc (1 hunks)
.cursor/rules/200-development-testing-workflow.mdc (3 hunks)
.cursor/rules/230-api-route-tests.mdc (1 hunks)
.cursor/rules/800-api-documentation-guidelines.mdc (1 hunks)
AGENTS.md (7 hunks)
API.md (1 hunks)
README.md (6 hunks)
SPEC.md (5 hunks)
TESTING.md (4 hunks)
blockscout_mcp_server/api/dependencies.py (1 hunks)
blockscout_mcp_server/api/helpers.py (1 hunks)
blockscout_mcp_server/api/routes.py (1 hunks)
blockscout_mcp_server/llms.txt (1 hunks)
blockscout_mcp_server/server.py (1 hunks)
blockscout_mcp_server/templates/index.html (1 hunks)
pyproject.toml (1 hunks)
tests/api/test_routes.py (1 hunks)
tests/test_server.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (11)

`pyproject.toml`: If any new package needs to be installed it needs to be done w...

pyproject.toml: If any new package needs to be installed it needs to be done with 'sudo which uv pip install --system ""' command. Don't forget to update pyproject.toml with the new package.

📄 Source: CodeRabbit Inference Engine (.cursor/rules/010-implementation-rules.mdc)