diff --git a/VERSION b/VERSION index 09a3acf..7ceb040 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.6.0 \ No newline at end of file +0.6.1 \ No newline at end of file diff --git a/VERSION.meta b/VERSION.meta index ad392c3..4d2c12a 100644 --- a/VERSION.meta +++ b/VERSION.meta @@ -4,7 +4,7 @@ MAJOR=0 MINOR=6 -PATCH=0 +PATCH=1 DEV_NUMBER= BUILD_NUMBER= BRANCH=main diff --git a/docs/articles/users/tutorials/02-environments/01-manage-envs.md b/docs/articles/users/tutorials/02-environments/01-manage-envs.md index 184b8b1..d2d2390 100644 --- a/docs/articles/users/tutorials/02-environments/01-manage-envs.md +++ b/docs/articles/users/tutorials/02-environments/01-manage-envs.md @@ -101,14 +101,14 @@ You can maintain multiple environments for different projects: ```bash # Project-specific environments -hatch env create project-a --description "Environment for Project A" --python-version 3.11 -hatch env create project-b --description "Environment for Project B" --python-version 3.12 +hatch env create project_a --description "Environment for Project A" --python-version 3.11 +hatch env create project_b --description "Environment for Project B" --python-version 3.12 # Switch between them as needed -hatch env use project-a +hatch env use project_a # Work on project A... -hatch env use project-b +hatch env use project_b # Work on project B... ``` @@ -120,22 +120,22 @@ Create three environments with different Python versions, switch between them, a ```bash # Create environments -hatch env create env-311 --python-version 3.11 --description "Python 3.11 environment" -hatch env create env-312 --python-version 3.12 --description "Python 3.12 environment" -hatch env create env-313 --python-version 3.13 --description "Python 3.13 environment" +hatch env create env_311 --python-version 3.11 --description "Python 3.11 environment" +hatch env create env_312 --python-version 3.12 --description "Python 3.12 environment" +hatch env create env_313 --python-version 3.13 --description "Python 3.13 environment" # Switch between them -hatch env use env-311 -hatch env current # Should show env-311 +hatch env use env_311 +hatch env current # Should show env_311 -hatch env use env-312 -hatch env current # Should show env-312 +hatch env use env_312 +hatch env current # Should show env_312 # List to see all three hatch env list # Remove one -hatch env remove env-313 +hatch env remove env_313 ``` diff --git a/docs/articles/users/tutorials/03-author-package/01-generate-template.md b/docs/articles/users/tutorials/03-author-package/01-generate-template.md index 5ef70ee..0d15e94 100644 --- a/docs/articles/users/tutorials/03-author-package/01-generate-template.md +++ b/docs/articles/users/tutorials/03-author-package/01-generate-template.md @@ -154,5 +154,5 @@ cat described-package/hatch_metadata.json The description should appear in the metadata and README files. -> Previous: [Environment Management Checkpoint](../02-environments/03-checkpoint.md) -> Next: [Edit Metadata](02-edit-metadata.md) +> Previous: [Environment Management Checkpoint](../02-environments/03-checkpoint.md) +> Next: [Implement Functionality](02-implement-functionality.md) diff --git a/docs/articles/users/tutorials/03-author-package/02-edit-metadata.md b/docs/articles/users/tutorials/03-author-package/02-edit-metadata.md deleted file mode 100644 index 0270661..0000000 --- a/docs/articles/users/tutorials/03-author-package/02-edit-metadata.md +++ /dev/null @@ -1,231 +0,0 @@ -# 02: Edit Metadata - ---- -**Concepts covered:** - -- Hatch package metadata schema structure and validation -- Required and optional metadata fields -- Dependency specification and compatibility constraints -- Package versioning and licensing - -**Skills you will practice:** - -- Editing the hatch_metadata.json file -- Understanding schema validation requirements -- Configuring dependencies and compatibility settings -- Setting up proper package metadata for distribution - ---- - -This article covers editing the `hatch_metadata.json` file that defines your package's metadata and dependencies. - -## Understanding the Metadata Schema - -The `hatch_metadata.json` file follows the schema defined in `Hatch-Schemas/package/v1.2.0/hatch_pkg_metadata_schema.json`. - -The package's metadata are not critical to the package's functionality but are critical to its distribution and installation by the Hatch ecosystem. For example, [dependencies](#step-3-define-dependencies) information are leveraged during the package's installation to automatically resolve and install any required dependencies. The list of [tools](#step-5-define-tools-and-citations) your package provides is used during package submission to the online registry to confirm the content of your mcp server. Except these, the metadata are not used at runtime simply helps providing information to users and transparency to the community. - -## Step 1: Required Fields - -Every package must include these fields: - -```json -{ - "package_schema_version": "1.2.0", - "name": "package_name", - "version": "0.1.0", - "entry_point": "hatch_mcp_server_entry.py", - "description": "Package description", - "tags": [], - "author": { - "name": "Author Name" - }, - "license": { - "name": "MIT" - } -} -``` - -## Step 2: Configure Package Information - -Edit the basic package information: - -```json -{ - "package_schema_version": "1.2.0", - "name": "my_awesome_package", - "version": "1.0.0", - "description": "An awesome MCP server package that does amazing things", - "tags": ["mcp", "server", "automation", "productivity"], - "author": { - "name": "Your Name", - "email": "your.email@example.com" - }, - "contributors": [ - { - "name": "Contributor Name", - "email": "contributor@example.com" - } - ], - "license": { - "name": "MIT", - "uri": "https://opensource.org/licenses/MIT" - }, - "repository": "https://github.com/yourusername/my-awesome-package", - "documentation": "https://your-docs-site.com", - "entry_point": "hatch_mcp_server_entry.py" -} -``` - -## Step 3: Define Dependencies - -Configure different types of dependencies: - -```json -{ - "dependencies": { - "hatch": [ - { - "name": "another_hatch_package", - "version_constraint": ">=1.0.0" - } - ], - "python": [ - { - "name": "requests", - "version_constraint": ">=2.28.0", - "package_manager": "pip" - }, - { - "name": "numpy", - "version_constraint": "==1.24.0", - "package_manager": "pip" - } - ], - "system": [ - { - "name": "curl", - "version_constraint": ">=7.0.0", - "package_manager": "apt" - } - ], - "docker": [ - { - "name": "redis", - "version_constraint": ">=7.0.0", - "registry": "dockerhub" - } - ] - } -} -``` - -### Version Constraint Patterns - -- `==1.0.0` - Exact version -- `>=1.0.0` - Minimum version -- `<=2.0.0` - Maximum version -- `!=1.5.0` - Exclude specific version - -## Step 4: Set Compatibility Requirements - -Define compatibility constraints: - -```json -{ - "compatibility": { - "hatchling": ">=0.1.0", - "python": ">=3.8" - } -} -``` - -## Step 5: Define Tools and Citations - -Document the tools your package provides: - -```json -{ - "tools": [ - { - "name": "search_web", - "description": "Search the web for information" - }, - { - "name": "analyze_data", - "description": "Analyze data sets and generate reports" - } - ], - "citations": { - "origin": "Based on the WebSearch project by Example Corp", - "mcp": "Implements MCP specification version 1.0" - } -} -``` - -## Step 6: Validate Metadata Structure - -The schema enforces several validation rules: - -- **Package names** must match pattern `^[a-z0-9_]+$` -- **Versions** must follow semantic versioning `^\d+(\.\d+)*$` -- **Email addresses** must be valid email format -- **URIs** must be valid URI format -- **Version constraints** must match pattern `^\s*(==|>=|<=|!=)\s*\d+(\.\d+)*$` - -**Exercise:** -Create a complete metadata file for a hypothetical "weather-service" package that depends on the requests library and provides weather-related tools. - -
-Solution - -```json -{ - "package_schema_version": "1.2.0", - "name": "weather_service", - "version": "1.0.0", - "description": "MCP server for weather information and forecasting", - "tags": ["weather", "forecast", "api", "mcp"], - "author": { - "name": "Weather Developer", - "email": "dev@weather-service.com" - }, - "license": { - "name": "MIT", - "uri": "https://opensource.org/licenses/MIT" - }, - "repository": "https://github.com/weather/weather-service", - "entry_point": "hatch_mcp_server_entry.py", - "dependencies": { - "python": [ - { - "name": "requests", - "version_constraint": ">=2.28.0", - "package_manager": "pip" - } - ] - }, - "compatibility": { - "python": ">=3.8" - }, - "tools": [ - { - "name": "get_current_weather", - "description": "Get current weather for a location" - }, - { - "name": "get_forecast", - "description": "Get weather forecast for a location" - } - ], - "citations": { - "origin": "Weather data provided by OpenWeather API", - "mcp": "Implements MCP specification for weather services" - } -} -``` - -
- -> Previous: [Generate Template](01-generate-template.md) -> Next: [Validate and Install](03-validate-and-install.md) diff --git a/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md b/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md new file mode 100644 index 0000000..5cbdc32 --- /dev/null +++ b/docs/articles/users/tutorials/03-author-package/02-implement-functionality.md @@ -0,0 +1,292 @@ +# 02: Implement Functionality + +--- +**Concepts covered:** + +- Transforming template code into functional MCP server implementation +- Adding Python dependencies and imports to MCP servers +- Implementing multiple tools with proper type hints and documentation +- Error handling and validation in MCP tool functions +- Testing MCP server functionality before packaging + +**Skills you will practice:** + +- Writing MCP tool functions with FastMCP decorators +- Adding external dependencies like numpy to enhance functionality +- Creating comprehensive docstrings for LLM tool understanding +- Implementing error handling and input validation +- Testing MCP server tools locally before installation + +--- + +This article covers transforming the generated template into a functional MCP server by implementing actual tools, similar to the arithmetic package example. + +## Step 1: Plan Your Implementation + +Before writing code, plan what your MCP server will do. For this tutorial, we'll implement an arithmetic server that provides: + +- Basic arithmetic operations (add, subtract, multiply, divide) +- Advanced operations using numpy (power function) +- Proper error handling (division by zero) +- Clear documentation for LLM understanding + +## Step 2: Implement Core MCP Server Logic + +Replace the template content in `mcp_server.py` with functional arithmetic tools: + +```python +import numpy as np +from mcp.server.fastmcp import FastMCP + +mcp = FastMCP("ArithmeticTools", log_level="WARNING") + +@mcp.tool() +def add(a: float, b: float) -> float: + """Add two numbers together. + + Args: + a (float): First number. + b (float): Second number. + + Returns: + float: Sum of a and b. + """ + return a + b + +@mcp.tool() +def subtract(a: float, b: float) -> float: + """Subtract second number from first number. + + Args: + a (float): First number. + b (float): Second number. + + Returns: + float: Difference (a - b). + """ + return a - b + +@mcp.tool() +def multiply(a: float, b: float) -> float: + """Multiply two numbers together. + + Args: + a (float): First number. + b (float): Second number. + + Returns: + float: Product of a and b. + """ + return a * b + +@mcp.tool() +def divide(a: float, b: float) -> float: + """Divide first number by second number. + + Args: + a (float): First number (dividend). + b (float): Second number (divisor). + + Returns: + float: Quotient (a / b). + """ + if b == 0: + raise ValueError("Cannot divide by zero") + + return a / b + +@mcp.tool() +def power(base: float, exponent: float) -> float: + """Raise a number to the power of another number. + + Args: + base (float): The base number. + exponent (float): The exponent (power). + + Returns: + float: Result of raising base to the power of exponent. + """ + return np.power(base, exponent) + +if __name__ == "__main__": + mcp.run() +``` + +## Step 3: Update Entry Point File + +Modify `hatch_mcp_server_entry.py` to use proper citations and naming: + +```python +from hatch_mcp_server import HatchMCP +from mcp_server import mcp + +hatch_mcp = HatchMCP("ArithmeticTools", + fast_mcp=mcp, + origin_citation="Your Name, \"Origin: Arithmetic MCP Server Tutorial\", 2025", + mcp_citation="Your Name, \"MCP: Arithmetic Tools Implementation\", 2025") + +if __name__ == "__main__": + hatch_mcp.server.run() +``` + +## Step 4: Key Implementation Principles + +**Type Hints**: Always use proper type hints for parameters and return values. This helps LLMs understand expected input/output types. + +**Docstrings**: Write comprehensive docstrings following the Google style. The docstring is crucial as LLMs use it to understand tool functionality. + +**Error Handling**: Implement appropriate error handling for edge cases (like division by zero). + +**Output Types**: Be aware that the final consumer of the tools' output is an LLM. Therefore, even if you returns complex types from your tools, the LLM will only see the string representation of that output. Hence, it is often a good idea to: + +- return primitive types (strings, numbers, booleans) from your tools +- return JSON-serializable types (dicts, lists) from your tools (see [below](#complex-return-types)) +- implement a `__str__` method where possible for complex return types. + +## Step 5: Common Implementation Patterns + +### Adding More Dependencies + +If your implementation requires additional Python packages, add them to your imports: + +```python +import numpy as np +import requests # For HTTP requests +import json # For JSON processing +from datetime import datetime # For date/time operations +``` + +However, if you want your MCP server to work for anyone out of the box, you must leverage the dependency resolution capabilities of Hatch. This is done by editing the `hatch_metadata.json` file as described in the next article. + +### Complex Return Types + +For tools that return structured data, use appropriate type hints: + +```python +from typing import Dict, List + +@mcp.tool() +def get_statistics(numbers: List[float]) -> Dict[str, float]: + """Calculate statistics for a list of numbers. + + Args: + numbers (List[float]): List of numbers to analyze. + + Returns: + Dict[str, float]: Dictionary containing mean, median, std deviation. + """ + if not numbers: + raise ValueError("Numbers list cannot be empty") + + return { + "mean": np.mean(numbers), + "median": np.median(numbers), + "std_dev": np.std(numbers) + } +``` + +### Input Validation Best Practices + +Always validate inputs to provide clear error messages: + +```python +@mcp.tool() +def safe_divide(a: float, b: float) -> float: + """Safely divide two numbers with validation. + + Args: + a (float): Dividend. + b (float): Divisor. + + Returns: + float: Result of division. + """ + # Type validation (FastMCP handles this automatically) + # Range validation + if b == 0: + raise ValueError("Division by zero is not allowed") + + # Additional validation for edge cases + if abs(b) < 1e-10: + raise ValueError("Divisor too close to zero for safe division") + + return a / b +``` + +Errors raised in tool functions are propagated back to the LLM, so it's important to provide clear, actionable error messages. This can help the LLM understand what went wrong in the tool call and maybe how to fix the arguments before retrying the tool call. + +**Exercise:** +Implement a different set of tools for a "text processing" MCP server that includes functions for string manipulation (uppercase, lowercase, reverse, word count). Include proper error handling for empty strings. + +
+Solution + +```python +from mcp.server.fastmcp import FastMCP + +mcp = FastMCP("TextProcessingTools", log_level="WARNING") + +@mcp.tool() +def to_uppercase(text: str) -> str: + """Convert text to uppercase. + + Args: + text (str): Input text to convert. + + Returns: + str: Text converted to uppercase. + """ + if not text: + raise ValueError("Input text cannot be empty") + return text.upper() + +@mcp.tool() +def to_lowercase(text: str) -> str: + """Convert text to lowercase. + + Args: + text (str): Input text to convert. + + Returns: + str: Text converted to lowercase. + """ + if not text: + raise ValueError("Input text cannot be empty") + return text.lower() + +@mcp.tool() +def reverse_text(text: str) -> str: + """Reverse the order of characters in text. + + Args: + text (str): Input text to reverse. + + Returns: + str: Text with characters in reverse order. + """ + if not text: + raise ValueError("Input text cannot be empty") + return text[::-1] + +@mcp.tool() +def word_count(text: str) -> int: + """Count the number of words in text. + + Args: + text (str): Input text to count words in. + + Returns: + int: Number of words in the text. + """ + if not text: + return 0 + return len(text.split()) + +if __name__ == "__main__": + mcp.run() +``` + +
+ +> Previous: [Generate Template](01-generate-template.md) +> Next: [Edit Metadata](03-edit-metadata.md) diff --git a/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md b/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md new file mode 100644 index 0000000..73188d5 --- /dev/null +++ b/docs/articles/users/tutorials/03-author-package/03-edit-metadata.md @@ -0,0 +1,321 @@ +# 03: Edit Metadata + +--- +**Concepts covered:** + +- Hatch package metadata schema structure and validation +- Required and optional metadata fields +- Dependency specification and compatibility constraints +- Package versioning and licensing + +**Skills you will practice:** + +- Editing the hatch_metadata.json file +- Understanding schema validation requirements +- Configuring dependencies and compatibility settings +- Setting up proper package metadata for distribution + +--- + +This article covers editing the `hatch_metadata.json` file that defines your package's metadata and dependencies. Now that you have implemented your MCP server functionality, you need to configure the metadata to properly describe your package and its dependencies. + +## Understanding the Metadata Schema + +The `hatch_metadata.json` file follows the schema defined in [Hatch-Schemas/packag](https://github.com/CrackingShells/Hatch-Schemas/blob/main/package/). The schemas are not well-defined yet and are subject to change. However, at the time of writing, the latest version is `v1.2.1`. + +The package's metadata are not critical to the package's functionality but are critical to its distribution (submission to the online registry) and installation by the Hatch ecosystem. For example, [dependencies](#step-3-define-dependencies) information are leveraged during the package's installation to automatically resolve and install any required dependencies. The list of [tools](#step-5-define-tools-and-citations) your package provides is used during package submission to the online registry to confirm the content of your mcp server. Except these, the metadata are not used at runtime simply helps providing information to users and transparency to the community. + +## Step 1: Required Fields + +Every package must include these fields: + +```json +{ + "package_schema_version": "1.2.1", + "name": "package_name", + "version": "0.1.0", + "entry_point": "hatch_mcp_server_entry.py", + "description": "Package description", + "tags": [], + "author": { + "name": "Author Name" + }, + "license": { + "name": "MIT" + } +} +``` + +## Step 2: Configure Package Information + +Edit the basic package information: + +```json +{ + "package_schema_version": "1.2.1", + "name": "my_awesome_package", + "version": "1.0.0", + "description": "An awesome MCP server package that does amazing things", + "tags": ["mcp", "server", "automation", "productivity"], + "author": { + "name": "Your Name", + "email": "your.email@example.com" + }, + "contributors": [ + { + "name": "Contributor Name", + "email": "contributor@example.com" + } + ], + "license": { + "name": "MIT", + "uri": "https://opensource.org/licenses/MIT" + }, + "repository": "https://github.com/yourusername/my-awesome-package", + "documentation": "https://your-docs-site.com", + "entry_point": "hatch_mcp_server_entry.py" +} +``` + +## Step 3: Define Dependencies + +Configure dependencies based on your implementation. For our arithmetic server that uses numpy: + +```json +{ + "dependencies": { + "hatch": [], + "python": [ + { + "name": "numpy", + "version_constraint": ">=2.2.0", + "package_manager": "pip" + } + ], + "system": [], + "docker": [] + } +} +``` + +### Dependency Types Explained + +**Hatch dependencies**: Other Hatch packages your server depends on + +```json +"hatch": [ + { + "name": "another_hatch_package", + "version_constraint": ">=1.0.0" + } +] +``` + +**Python dependencies**: Python packages installed via pip + +```json +"python": [ + { + "name": "requests", + "version_constraint": ">=2.28.0", + "package_manager": "pip" + } +] +``` + +**System dependencies**: OS-level packages (Linux only currently) + +```json +"system": [ + { + "name": "curl", + "version_constraint": ">=7.0.0", + "package_manager": "apt" + } +] +``` + +**Docker dependencies**: Container images for services + +```json +"docker": [ + { + "name": "redis", + "version_constraint": ">=7.0.0", + "registry": "dockerhub" + } +] +``` + +### Version Constraint Patterns + +- `==1.0.0` - Exact version +- `>=1.0.0` - Minimum version +- `<=2.0.0` - Maximum version +- `!=1.5.0` - Exclude specific version + +## Step 4: Set Compatibility Requirements + +Define compatibility constraints: + +```json +{ + "compatibility": { + "hatchling": ">=0.1.0", + "python": ">=3.8" + } +} +``` + +## Step 5: Define Tools and Citations + +Document the tools your package provides. For our arithmetic server: + +```json +{ + "tools": [ + { + "name": "add", + "description": "Add two numbers together." + }, + { + "name": "subtract", + "description": "Subtract one number from another." + }, + { + "name": "multiply", + "description": "Multiply two numbers together." + }, + { + "name": "divide", + "description": "Divide one number by another." + }, + { + "name": "power", + "description": "Raise a number to the power of another number." + } + ], + "citations": { + "origin": "Your Name, \"Origin: Arithmetic MCP Server Tutorial\", 2025", + "mcp": "Your Name, \"MCP: Arithmetic Tools Implementation\", 2025" + } +} +``` + +**Important**: The tools list should match exactly the functions you decorated with `@mcp.tool()` in your implementation. + +## Step 6: Complete Example + +Here's a complete `hatch_metadata.json` file for our arithmetic package: + +```json +{ + "package_schema_version": "1.2.1", + "name": "arithmetic_tutorial_pkg", + "version": "1.0.0", + "description": "A tutorial package demonstrating arithmetic operations with MCP", + "tags": ["tutorial", "math", "arithmetic", "mcp"], + "author": { + "name": "Your Name", + "email": "your.email@example.com" + }, + "license": { + "name": "MIT" + }, + "entry_point": "hatch_mcp_server_entry.py", + "dependencies": { + "hatch": [], + "python": [ + { + "name": "numpy", + "version_constraint": ">=2.2.0", + "package_manager": "pip" + } + ], + "system": [], + "docker": [] + }, + "compatibility": { + "python": ">=3.8" + }, + "tools": [ + {"name": "add", "description": "Add two numbers together."}, + {"name": "subtract", "description": "Subtract one number from another."}, + {"name": "multiply", "description": "Multiply two numbers together."}, + {"name": "divide", "description": "Divide one number by another."}, + {"name": "power", "description": "Raise a number to the power of another number."} + ], + "citations": { + "origin": "Your Name, \"Origin: Arithmetic MCP Server Tutorial\", 2025", + "mcp": "Your Name, \"MCP: Arithmetic Tools Implementation\", 2025" + } +} +``` + +## Step 7: Validate Metadata Structure + +The schema enforces several validation rules: + +- **Package names** must match pattern `^[a-z0-9_]+$` (lowercase alphanumeric + underscore) +- **Versions** must follow semantic versioning `^\d+(\.\d+)*$` +- **Email addresses** must be valid email format +- **URIs** must be valid URI format +- **Version constraints** must match pattern `^\s*(==|>=|<=|!=)\s*\d+(\.\d+)*$` + +**Exercise:** +Create a complete metadata file for a hypothetical "weather-service" package that depends on the requests library and provides weather-related tools. + +
+Solution +Yours might differ, but here's one example: + +```json +{ + "package_schema_version": "1.2.1", + "name": "weather_service", + "version": "1.0.0", + "description": "MCP server for weather information and forecasting", + "tags": ["weather", "forecast", "api", "mcp"], + "author": { + "name": "Weather Developer", + "email": "dev@weather-service.com" + }, + "license": { + "name": "MIT", + "uri": "https://opensource.org/licenses/MIT" + }, + "repository": "https://github.com/weather/weather-service", + "entry_point": "hatch_mcp_server_entry.py", + "dependencies": { + "python": [ + { + "name": "requests", + "version_constraint": ">=2.28.0", + "package_manager": "pip" + } + ] + }, + "compatibility": { + "python": ">=3.8" + }, + "tools": [ + { + "name": "get_current_weather", + "description": "Get current weather for a location" + }, + { + "name": "get_forecast", + "description": "Get weather forecast for a location" + } + ], + "citations": { + "origin": "Weather data provided by OpenWeather API", + "mcp": "Implements MCP specification for weather services" + } +} +``` + +
+ +> Previous: [Implement Functionality](02-implement-functionality.md) +> Next: [Validate and Install](04-validate-and-install.md) diff --git a/docs/articles/users/tutorials/03-author-package/03-validate-and-install.md b/docs/articles/users/tutorials/03-author-package/04-validate-and-install.md similarity index 90% rename from docs/articles/users/tutorials/03-author-package/03-validate-and-install.md rename to docs/articles/users/tutorials/03-author-package/04-validate-and-install.md index cf3924c..5dcffa4 100644 --- a/docs/articles/users/tutorials/03-author-package/03-validate-and-install.md +++ b/docs/articles/users/tutorials/03-author-package/04-validate-and-install.md @@ -1,4 +1,4 @@ -# 03: Validate and Install +# 04: Validate and Install --- **Concepts covered:** @@ -17,7 +17,7 @@ ## Understanding Validation -This article covers validating your package and installing it into a Hatch environment. +This article covers validating your package and installing it into a Hatch environment. Now that you have implemented functionality and configured metadata, it's time to validate and test your complete package. The `validate` CLI subcommand constructs a `HatchPackageValidator` with `version='latest'` and `allow_local_dependencies=True`, passing the environment manager's registry data into the validator. On success the command exits with code 0; on failure it exits with code 1 and prints grouped validation errors (the CLI prints category-level errors except for the special `valid` and `metadata` categories). @@ -26,7 +26,7 @@ The `validate` CLI subcommand constructs a `HatchPackageValidator` with `version Before installing or submitting your package to the online registry, validate your package meets Hatch requirements: ```bash -hatch validate /path/to/my-package +hatch validate /path/to/my_package ``` The validation process checks: @@ -39,7 +39,7 @@ The validation process checks: ### Successful Validation ```txt -Package validation SUCCESSFUL: /path/to/my-package +Package validation SUCCESSFUL: /path/to/my_package ``` The command will exit with status code 0 when validation succeeds. @@ -47,7 +47,7 @@ The command will exit with status code 0 when validation succeeds. ### Failed Validation ```txt -Package validation FAILED: /path/to/my-package +Package validation FAILED: /path/to/my_package ``` When validation fails the CLI prints a failure line and then — if detailed results are available — lists errors grouped by category. The CLI deliberately skips printing the `valid` and `metadata` categories in that grouped output and only prints categories which are invalid and include an `errors` list. @@ -55,7 +55,7 @@ When validation fails the CLI prints a failure line and then — if detailed res Example failure output (category grouping): ```txt -Package validation FAILED: C:\path\to\my-package +Package validation FAILED: C:\path\to\my_package Entry Point Errors: - Missing required field 'entry_point' @@ -75,7 +75,7 @@ The command will exit with status code 1 when validation fails. ```json // ❌ Invalid - contains hyphens -"name": "my-package" +"name": "my_package" // ✅ Valid - uses underscores "name": "my_package" @@ -113,7 +113,7 @@ Once validation passes, install the package: hatch env use my_dev_env # Install the package -hatch package add /path/to/my-package +hatch package add /path/to/my_package ``` The installation process involves: @@ -145,7 +145,7 @@ Output should show your package: ```txt Packages in environment 'my_dev_env': -my_package (1.0.0) Hatch compliant: true source: file:///path/to/my-package location: /env/path/my_package +my_package (1.0.0) Hatch compliant: true source: file:///path/to/my_package location: /env/path/my_package ``` ## Step 5: Test Package Functionality @@ -191,5 +191,5 @@ hatch package list -> Previous: [Edit Metadata](02-edit-metadata.md) -> Next: [Checkpoint](04-checkpoint.md) +> Previous: [Edit Metadata](03-edit-metadata.md) +> Next: [Checkpoint](05-checkpoint.md) diff --git a/docs/articles/users/tutorials/03-author-package/04-checkpoint.md b/docs/articles/users/tutorials/03-author-package/05-checkpoint.md similarity index 76% rename from docs/articles/users/tutorials/03-author-package/04-checkpoint.md rename to docs/articles/users/tutorials/03-author-package/05-checkpoint.md index b3c72d5..6c67fbd 100644 --- a/docs/articles/users/tutorials/03-author-package/04-checkpoint.md +++ b/docs/articles/users/tutorials/03-author-package/05-checkpoint.md @@ -3,7 +3,9 @@ **What you've accomplished:** - Generated package templates with customization options -- Mastered the hatch_metadata.json schema and field requirements +- Implemented functional MCP server tools with proper error handling +- Added external dependencies (numpy) to enhance functionality +- Configured comprehensive package metadata following the schema - Learned validation processes and error resolution - Successfully installed locally developed packages diff --git a/hatch/template_generator.py b/hatch/template_generator.py index 55d4e50..5977bde 100644 --- a/hatch/template_generator.py +++ b/hatch/template_generator.py @@ -79,7 +79,7 @@ def generate_metadata_json(package_name: str, description: str = ""): dict: Metadata dictionary. """ return { - "package_schema_version": "1.2.0", + "package_schema_version": "1.2.1", "name": package_name, "version": "0.1.0", "description": description or f"A Hatch package for {package_name}", @@ -91,7 +91,11 @@ def generate_metadata_json(package_name: str, description: str = ""): "license": { "name": "MIT" }, - "entry_point": "hatch_mcp_server_entry.py", + "entry_point": + { + "mcp_server": "mcp_server.py", + "hatch_mcp_server": "hatch_mcp_server_entry.py" + }, "tools": [ { "name": "example_tool", diff --git a/pyproject.toml b/pyproject.toml index 8dda278..0b5d27d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,7 +23,7 @@ dependencies = [ "packaging>=20.0", "docker>=7.1.0", - "hatch_validator @ git+https://github.com/CrackingShells/Hatch-Validator.git@v0.6.3" + "hatch_validator @ git+https://github.com/CrackingShells/Hatch-Validator.git@v0.7.0" ] [project.scripts]