feat(mamba-mcp-core): add shared utility package#3
Conversation
Add SAP HANA MCP server to README.md and CLAUDE.md with complete package description, architecture details, and repository structure updates. Also document mamba-mcp-fs utility modules (content.py, errors.py).
- Created internal/docs/codebase-analysis.md with comprehensive analysis of all 4 packages, including architecture overview, critical files, patterns, challenges, and recommendations - Updated CLAUDE.md with Key Patterns to Follow (7 core patterns for server packages), Testing Conventions, and Known Inconsistencies to guide future development - Updated README.md with Architecture section explaining the shared FastMCP + layered tool pattern and tech stack
…mba_mcp_hana Resolve module name asymmetry where mamba-mcp-hana was the only package that didn't follow the 1:1 naming convention (it used mamba_mcp_sap_hana with an extra sap_ prefix). All other packages map directly: mamba-mcp-pg → mamba_mcp_pg, mamba-mcp-fs → mamba_mcp_fs. Changes: - Rename src/mamba_mcp_sap_hana/ → src/mamba_mcp_hana/ - Update pyproject.toml entry point and build config - Update all imports across source and test files - Update CLAUDE.md, README.md, and codebase-analysis.md BREAKING CHANGE: Module import path changed from mamba_mcp_sap_hana to mamba_mcp_hana
Create mamba-mcp-core to extract duplicated code from server packages: - cli.py: validate_env_file, resolve_default_env_file, setup_logging - config.py: module-level env file path state management - errors.py: flat ToolError model + create_tool_error factory with server-specific suggestions_map parameter - fuzzy.py: Levenshtein distance + find_similar_names with scaled threshold (max(2, min(len//2, 5))) — standardizes PG vs HANA approach - transport.py: normalize_transport accepting both "http" and "streamable-http" Includes 51 tests covering all modules. Addresses Challenges #3 (code duplication) and #6 (fuzzy matching inconsistency).
There was a problem hiding this comment.
Pull request overview
This PR introduces the mamba-mcp-core shared utilities package to address code duplication across server packages (Challenge #3) and standardizes fuzzy matching with HANA's scaled threshold strategy (Challenge #6). The PR also completes the HANA module rename from mamba_mcp_sap_hana to mamba_mcp_hana for naming consistency.
Changes:
- Creates new
mamba-mcp-corepackage with 5 utility modules (cli, config, errors, fuzzy, transport) and 51 tests - Renames HANA module from
mamba_mcp_sap_hanatomamba_mcp_hanaacross 32 Python files - Updates workspace configuration to include the new core package
Reviewed changes
Copilot reviewed 51 out of 60 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/mamba-mcp-core/pyproject.toml | New shared utilities package configuration with pydantic and typer dependencies |
| packages/mamba-mcp-core/src/mamba_mcp_core/*.py | Five utility modules: CLI helpers, config state, error handling, fuzzy matching, transport normalization |
| packages/mamba-mcp-core/tests/*.py | Complete test coverage with 5 test modules covering all utility functions |
| packages/mamba-mcp-hana/src/mamba_mcp_hana/**/*.py | Renamed module imports from mamba_mcp_sap_hana to mamba_mcp_hana |
| packages/mamba-mcp-hana/tests/**/*.py | Updated test imports to use new mamba_mcp_hana module name |
| packages/mamba-mcp-hana/pyproject.toml | Updated entry point and build configuration for renamed module |
| pyproject.toml | Added mamba-mcp-core to workspace configuration |
| uv.lock | Added mamba-mcp-core package with dependencies |
| README.md, CLAUDE.md | Added documentation for new core package and updated architecture section |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| def find_similar_names( | ||
| name: str, | ||
| candidates: list[str], | ||
| max_results: int = 3, | ||
| ) -> list[str]: |
There was a problem hiding this comment.
The naming inconsistency between find_similar_names (core) and suggest_similar (HANA) will create confusion when migrating servers to use the shared utility. Since this PR doesn't yet migrate HANA to use core's implementation, consider aligning the function names before adoption begins.
The HANA name suggest_similar may be more descriptive as it indicates the purpose (providing suggestions) rather than the mechanism (finding similar names).
| def create_tool_error( | ||
| code: str, | ||
| message: str, | ||
| tool_name: str, | ||
| input_received: dict[str, Any] | None = None, | ||
| context: dict[str, Any] | None = None, | ||
| suggestion: str | None = None, | ||
| suggestions_map: dict[str, str] | None = None, | ||
| ) -> ToolError: |
There was a problem hiding this comment.
The create_tool_error function signature differs from the existing HANA implementation. The core version adds a suggestions_map parameter, while HANA's version directly uses the module-level ERROR_SUGGESTIONS dict. This creates an API incompatibility - if HANA were to import from core, existing call sites would break.
Consider either:
- Making
suggestions_mapa required parameter and updating the PR description to note this is a breaking change requiring migration - Having core's implementation match HANA's signature exactly, then add a separate
create_tool_error_with_map()function for the new pattern
The current hybrid approach will cause confusion when servers attempt to adopt the shared utilities.
Summary
mamba-mcp-coreshared utility package to eliminate code duplication across servers (Challenge feat(mamba-mcp-core): add shared utility package #3)ToolErrorflat model withsuggestions_mapparameter for server-specific error codesnormalize_transport()to accept both"http"and"streamable-http"Modules
cli.pyvalidate_env_file,resolve_default_env_file,setup_loggingconfig.py_env_file_pathstate managementerrors.pyToolErrormodel +create_tool_errorfactoryfuzzy.pylevenshtein_distance+find_similar_names(scaled threshold)transport.pynormalize_transportTest plan
Depends on: PR #2 (HANA rename)