feat: bootstrap MCP server framework (bootstrap_mcp_framework) by wryyyds7 · Pull Request #145 · antgroup/YASA-Engine

wryyyds7 · 2026-07-21T06:10:53Z

Implement the unified MCP Server framework as the runtime base for all upcoming YASA MCP tools (Issue #129).

Framework:

Dual transport: stdio (default) / streamable-http
Tool registration via @mcp_tool decorator + auto-discovery
Unified input validation (Pydantic), error handling, logging (stderr)
Health check endpoint GET /healthz in HTTP mode
Built-in demo tool ping returning server status

Modules:

yasa_mcp/config.py: CLI args + env var parsing
yasa_mcp/server.py: FastMCP lifecycle management
yasa_mcp/registry.py: decorator-based tool auto-registration
yasa_mcp/transport/http.py: streamable-http + /healthz
yasa_mcp/tools/ping.py: demo health-check tool
yasa_mcp/errors.py: unified error codes
yasa_mcp/logging_config.py: stderr logging with level control

Tests (44 passing):

test_registry.py: tool registration, auto-discovery, schema
test_validation.py: param validation, error handling
test_logging.py: stderr output, format, level filtering
test_config.py: CLI parsing, env vars, error exit

Docs:

docs/mcp/requirements.md: functional/non-functional requirements
docs/mcp/system-design.md: architecture, module design, data flow
docs/mcp/development-guide.md: step-by-step implementation guide
yasa_mcp/README.md: usage + Claude Desktop/Cline config examples

Implement the unified MCP Server framework as the runtime base for all upcoming YASA MCP tools (Issue antgroup#129). Framework: - Dual transport: stdio (default) / streamable-http - Tool registration via @mcp_tool decorator + auto-discovery - Unified input validation (Pydantic), error handling, logging (stderr) - Health check endpoint GET /healthz in HTTP mode - Built-in demo tool ping returning server status Modules: - yasa_mcp/config.py: CLI args + env var parsing - yasa_mcp/server.py: FastMCP lifecycle management - yasa_mcp/registry.py: decorator-based tool auto-registration - yasa_mcp/transport/http.py: streamable-http + /healthz - yasa_mcp/tools/ping.py: demo health-check tool - yasa_mcp/errors.py: unified error codes - yasa_mcp/logging_config.py: stderr logging with level control Tests (44 passing): - test_registry.py: tool registration, auto-discovery, schema - test_validation.py: param validation, error handling - test_logging.py: stderr output, format, level filtering - test_config.py: CLI parsing, env vars, error exit Docs: - docs/mcp/requirements.md: functional/non-functional requirements - docs/mcp/system-design.md: architecture, module design, data flow - docs/mcp/development-guide.md: step-by-step implementation guide - yasa_mcp/README.md: usage + Claude Desktop/Cline config examples

gemini-code-assist

Code Review

This pull request bootstraps the YASA MCP Server framework, establishing a unified base for program analysis tools with support for both stdio and HTTP transport modes, a dynamic tool registration and discovery mechanism, and a comprehensive test suite. The reviewer provided valuable feedback to enhance robustness and code quality, including: preventing duplicate tool registration by validating module names; using Starlette's public add_route API instead of directly modifying app.routes; passing the configured CLI log level to the HTTP server; resolving a potential fallback bug with empty string messages in errors.py; converting repo_root to an absolute path to avoid path resolution issues; refining the logger namespace check; and cleaning up unused imports, deprecated event loop calls, and placeholder comments.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-07-21T06:12:44Z

+        for attr_name in dir(module):  # 遍历模块中的所有属性
+            attr = getattr(module, attr_name)
+            if callable(attr) and hasattr(attr, _MCP_TOOL_META_ATTR):  #  找到可调用且有mcptoolmeta的属性的对象


To prevent duplicate tool registration, ensure that the function being registered was actually defined in the module currently being scanned. If a tool module imports another tool (e.g., from yasa_mcp.tools.ping import ping), dir(module) will contain that imported tool, causing it to be registered multiple times. Checking getattr(attr, '__module__', None) == full_name resolves this issue.

for attr_name in dir(module): # 遍历模块中的所有属性 attr = getattr(module, attr_name) if ( callable(attr) and hasattr(attr, _MCP_TOOL_META_ATTR) and getattr(attr, "__module__", None) == full_name ): # 找到在本模块中定义且有mcptoolmeta属性的对象

gemini-code-assist · 2026-07-21T06:12:44Z

+
+from fastmcp import FastMCP
+from starlette.responses import JSONResponse
+from starlette.routing import Route


Remove the unused Route import since /healthz can be registered using app.add_route.

gemini-code-assist · 2026-07-21T06:12:44Z

+    # 追加 /healthz 路由
+    health_route = Route("/healthz", healthz, methods=["GET"])
+    app.routes.insert(0, health_route)


Directly manipulating app.routes is an implementation detail of Starlette. It is safer and cleaner to use the public add_route API of the Starlette application, which also allows removing the unused Route import from starlette.routing.

Suggested change

# 追加 /healthz 路由

health_route = Route("/healthz", healthz, methods=["GET"])

app.routes.insert(0, health_route)

# 追加 /healthz 路由

app.add_route("/healthz", healthz, methods=["GET"])

gemini-code-assist · 2026-07-21T06:12:44Z

+    return app
+
+
+async def run_http(mcp: FastMCP, port: int, host: str = "0.0.0.0") -> None:


Accept the log_level parameter in run_http so that the ASGI server can respect the user's CLI configuration.

Suggested change

async def run_http(mcp: FastMCP, port: int, host: str = "0.0.0.0") -> None:

async def run_http(mcp: FastMCP, port: int, host: str = "0.0.0.0", log_level: str = "info") -> None:

gemini-code-assist · 2026-07-21T06:12:44Z

+    config = uvicorn.Config(
+        app,
+        host=host,
+        port=port,
+        log_level="info",
+    )


Pass the log_level parameter to uvicorn.Config instead of hardcoding it to 'info'.

Suggested change

config = uvicorn.Config(

app,

host=host,

port=port,

log_level="info",

)

config = uvicorn.Config(

app,

host=host,

port=port,

log_level=log_level,

)

gemini-code-assist · 2026-07-21T06:12:45Z

+    code = "TOOL_NOT_FOUND"
+    message = "Requested tool is not registered"
+
+# 还可以添加


Remove the trailing placeholder comment # 还可以添加 to keep the production codebase clean.

gemini-code-assist · 2026-07-21T06:12:45Z

+        async def my_tool(x: int) -> int:
+            return x * 2
+
+        result = asyncio.get_event_loop().run_until_complete(my_tool(5))


In Python 3.10+, asyncio.get_event_loop() can raise deprecation warnings or runtime errors if there is no running event loop. Use asyncio.run() instead, which is the modern and standard way to run coroutines in synchronous contexts.

Suggested change

result = asyncio.get_event_loop().run_until_complete(my_tool(5))

result = asyncio.run(my_tool(5))

gemini-code-assist · 2026-07-21T06:12:45Z

+from pydantic import ValidationError
+
+from yasa_mcp.registry import mcp_tool, auto_discover_tools
+from yasa_mcp.errors import ValidationError as YasaValidationError


The imports ValidationError from pydantic and ValidationError as YasaValidationError from yasa_mcp.errors are unused in this test file. They should be removed to keep the code clean.

Suggested change

from pydantic import ValidationError

from yasa_mcp.registry import mcp_tool, auto_discover_tools

from yasa_mcp.errors import ValidationError as YasaValidationError

from yasa_mcp.registry import mcp_tool, auto_discover_tools

gemini-code-assist · 2026-07-21T06:12:45Z

+    )
+
+    args = parser.parse_args(argv)
+    repo_root = os.environ.get("YASA_MCP_REPO_ROOT", "")


Convert repo_root to an absolute path using os.path.abspath. If a relative path is provided via the YASA_MCP_REPO_ROOT environment variable, it can lead to bugs if the application changes its working directory or spawns subprocesses in different contexts.

repo_root = os.environ.get("YASA_MCP_REPO_ROOT", "") if repo_root: repo_root = os.path.abspath(repo_root)

gemini-code-assist · 2026-07-21T06:12:45Z

+    if not name.startswith("yasa_mcp"):
+        name = f"yasa_mcp.{name}"


The check not name.startswith("yasa_mcp") is too loose. For example, a logger named "yasa_mcp_helper" would match this check and not be prefixed, even though it is not part of the "yasa_mcp" hierarchical namespace (which should be "yasa_mcp.helper"). Use a more precise check to ensure proper hierarchy.

Suggested change

if not name.startswith("yasa_mcp"):

name = f"yasa_mcp.{name}"

if name != "yasa_mcp" and not name.startswith("yasa_mcp."):

name = f"yasa_mcp.{name}"

wryyyds7 · 2026-07-21T06:14:22Z

wait,I don't finish it.

wryyyds7 · 2026-07-21T06:52:39Z

#129

- registry.py: prevent duplicate tool registration via __module__ check - http.py: use app.add_route() instead of direct app.routes manipulation - http.py: remove unused Route import - http.py + server.py: pass log_level to uvicorn instead of hardcoding - errors.py: fix empty string message fallback bug - test_registry.py: use asyncio.run() instead of deprecated get_event_loop() - test_validation.py: remove unused imports - config.py: convert repo_root to absolute path - logging_config.py: precise logger namespace check - pyproject.toml: fix build-backend to setuptools.build_meta - .gitignore: add .venv/ and Python project ignore rules

wryyyds7 requested review from AntJiuFo, Arielwyy and alipaydeshui as code owners July 21, 2026 06:10

gemini-code-assist Bot reviewed Jul 21, 2026

View reviewed changes

		return app


		async def run_http(mcp: FastMCP, port: int, host: str = "0.0.0.0") -> None:

	result = asyncio.get_event_loop().run_until_complete(my_tool(5))
	result = asyncio.run(my_tool(5))

		if not name.startswith("yasa_mcp"):
		name = f"yasa_mcp.{name}"

Uh oh!

Conversation

wryyyds7 commented Jul 21, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

wryyyds7 commented Jul 21, 2026

Uh oh!

wryyyds7 commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant