semantic-release & documentation

.commitlintrc.json

@@ -0,0 +1,27 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "type-enum": [
+      2,
+      "always",
+      [
+        "build",
+        "chore", 
+        "ci",
+        "docs",
+        "feat",
+        "fix",
+        "perf",
+        "refactor",
+        "revert",
+        "style",
+        "test"
+      ]
+    ],
+    "subject-case": [2, "never", ["start-case", "pascal-case", "upper-case"]],
+    "subject-empty": [2, "never"],
+    "subject-full-stop": [2, "never", "."],
+    "header-max-length": [2, "always", 72],
+    "body-max-line-length": [2, "always", 500]
+  }
+}

.github/workflows/commitlint.yml

@@ -0,0 +1,25 @@
+name: Commit Lint
+
+on:
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate PR commits with commitlint
+        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

.github/workflows/semantic-release.yml

@@ -0,0 +1,64 @@
+name: Semantic Release
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - name: Run tests
+        run: |
+          python -c "import hatch_mcp_server; print('Package imports successfully')"
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    steps:
+      - name: Generate GitHub App Token
+        id: generate_token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.SEMANTIC_RELEASE_APP_ID }}
+          private_key: ${{ secrets.SEMANTIC_RELEASE_PRIVATE_KEY }}
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ steps.generate_token.outputs.token }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "lts/*"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Verify npm audit
+        run: npm audit signatures
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
+        run: npx semantic-release

.gitignore

@@ -205,3 +205,12 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Node.js dependencies for semantic-release
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Semantic-release
+.semantic-release/

.releaserc.json

@@ -0,0 +1,62 @@
+{
+  "repositoryUrl": "https://github.com/CrackingShells/Hatch-MCP-Server",
+  "tagFormat": "v${version}",
+  "branches": [
+    "main",
+    {
+      "name": "dev",
+      "prerelease": "dev"
+    }
+  ],
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          {"type": "docs", "scope": "README", "release": "patch"},
+          {"type": "refactor", "release": "patch"},
+          {"type": "style", "release": "patch"},
+          {"type": "test", "release": false},
+          {"type": "chore", "release": false}
+        ]
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            {"type": "feat", "section": "Features"},
+            {"type": "fix", "section": "Bug Fixes"},
+            {"type": "docs", "section": "Documentation"},
+            {"type": "refactor", "section": "Code Refactoring"},
+            {"type": "perf", "section": "Performance Improvements"}
+          ]
+        }
+      }
+    ],
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md", "pyproject.toml"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "successComment": false,
+        "failComment": false,
+        "releasedLabels": false
+      }
+    ]
+  ]
+}

CHANGELOG.md

@@ -0,0 +1,11 @@
+## [0.3.0-dev.1](https://github.com/CrackingShells/Hatch-MCP-Server/compare/v0.2.0...v0.3.0-dev.1) (2025-09-06)
+
+
+### Features
+
+* migrate to semantic-release ([b8f8673](https://github.com/CrackingShells/Hatch-MCP-Server/commit/b8f867341f893a66688fedcf8231b4bf8ba674f0))
+
+
+### Documentation
+
+* first pass on documentation ([4a283b3](https://github.com/CrackingShells/Hatch-MCP-Server/commit/4a283b39e7d1f74d8a832f492093b026da0e03cd))

README.md

@@ -1,2 +1,174 @@
 # Hatch-MCP-Server
-The wrapper around MCP server for Hatch-related applications
+
+A wrapper around FastMCP servers that adds automatic citation capabilities for scientific transparency and attribution in MCP (Model Context Protocol) applications.
+
+## What is HatchMCP?
+
+HatchMCP enhances FastMCP servers by automatically exposing citation information as standardized MCP resources. This enables proper attribution for both original research/algorithms and MCP server implementations, which is critical for attribution in scientific computing and autonomous agent systems.
+
+**Key Features:**
+
+- 🔬 **Scientific Attribution**: Automatic citation resource registration
+- 🔄 **FastMCP Compatibility**: Works with existing FastMCP servers
+- 📋 **Standardized URIs**: Uses `citation://origin/` and `citation://mcp/` schemes
+- 🪶 **Lightweight**: Minimal overhead, zero configuration required
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install directly from the repository
+pip install git+https://github.com/CrackingShells/Hatch-MCP-Server.git
+
+# Or install local copy
+git clone https://github.com/CrackingShells/Hatch-MCP-Server.git
+cd Hatch-MCP-Server
+pip install .
+```
+
+### Basic Usage
+
+```python
+from hatch_mcp_server import HatchMCP
+
+# Create an MCP server with citation capabilities
+hatch_mcp = HatchMCP(
+    name="MyServer",
+    origin_citation="Smith, J. 'Original Algorithm', Nature, 2024",
+    mcp_citation="Your Name, 'MCP Implementation', GitHub, 2024"
+)
+
+# Add tools using FastMCP decorator syntax
+@hatch_mcp.server.tool()
+def process_data(data: str) -> str:
+    """Process data using the wrapped algorithm."""
+    hatch_mcp.logger.info(f"Processing: {data}")
+    return f"Processed: {data}"
+
+# Run the server
+if __name__ == "__main__":
+    hatch_mcp.server.run()
+```
+
+### Existing FastMCP Server
+
+Assuming you have an existing FastMCP server (`mcp_server.py`)
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+existing_server = FastMCP("my_existing_server")
+
+@existing_server.tool()
+def existing_function(data: str) -> str:
+    return f"Existing: {data}"
+```
+
+You can wrap it with HatchMCP:
+
+```python
+from mcp.server.fastmcp import FastMCP
+from hatch_mcp_server import HatchMCP
+
+from mcp_server import existing_server
+
+# Wrap with HatchMCP for citation capabilities
+hatch_mcp = HatchMCP(
+    name="my_existing_server",
+    fast_mcp=existing_server,
+    origin_citation="Original work citation",
+    mcp_citation="MCP implementation citation"
+)
+
+# Run the server
+if __name__ == "__main__":
+    hatch_mcp.server.run()
+```
+
+The server automatically exposes citation information through:
+
+- `citation://origin/MyServer` - Original algorithm citation
+- `citation://mcp/MyServer` - MCP implementation citation
+
+## Documentation
+
+📚 **[Complete Documentation](docs/articles/index.md)** - Full documentation table of contents and navigation guide
+
+### Quick Start Guides
+
+- **[Getting Started](docs/articles/users/GettingStarted.md)** - Installation, setup, and first steps
+- **[API Reference](docs/articles/users/APIReference.md)** - Complete API documentation
+- **[Citation System](docs/articles/users/CitationSystem.md)** - Understanding scientific attribution features
+- **[Examples](docs/articles/users/Examples.md)** - Practical usage patterns and code samples
+
+### Developer Resources
+
+- **[Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md)** - Complete development workflow and MCP-specific requirements
+- **[Architecture Overview](docs/articles/devs/architecture/Overview.md)** - Design principles and implementation details
+
+### I Want To
+
+- **🚀 Get started quickly** → [Installation & Quick Start](docs/articles/users/GettingStarted.md#installation)
+- **🔄 Wrap existing FastMCP servers** → [Basic Usage](docs/articles/users/GettingStarted.md#Wrapping-Existing-FastMCP-Servers)
+- **📖 Learn about citations** → [Citation System Guide](docs/articles/users/CitationSystem.md)
+- **🔍 Look up specific APIs** → [API Reference](docs/articles/users/APIReference.md)
+- **💡 See examples** → [Examples & Patterns](docs/articles/users/Examples.md)
+- **🛠️ Contribute code** → [Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md)
+- **🏗️ Understand design** → [Architecture Overview](docs/articles/devs/architecture/Overview.md)
+- **📋 Browse all docs** → [Documentation Table of Contents](docs/articles/index.md)
+
+## Why Use HatchMCP?
+
+### Scientific Transparency
+
+```python
+# Citation information is automatically available to MCP clients
+# citation://origin/ServerName -> "Smith, J. 'Algorithm X', Nature, 2024"
+# citation://mcp/ServerName -> "Your Name, 'MCP Implementation', 2024"
+```
+
+### Zero Configuration
+
+```python
+# Just wrap your server - citation resources are registered automatically
+hatch_mcp = HatchMCP("server_name", origin_citation="...", mcp_citation="...")
+# Use hatch_mcp.server exactly like FastMCP
+```
+
+### FastMCP Compatibility
+
+```python
+# Wrap existing FastMCP servers without changes
+existing_server = FastMCP("my_server")
+wrapped = HatchMCP("my_server", fast_mcp=existing_server, ...)
+```
+
+## Contributing
+
+We welcome contributions! Please see our comprehensive [Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md) for detailed guidelines covering development workflow, MCP compatibility requirements, and coding standards.
+
+### Overview
+
+1. **Fork and clone** the repository
+2. **Install dependencies**: `pip install -e .` and `npm install`
+3. **Create a feature branch**: `git checkout -b feat/your-feature`
+4. **Make changes** and add tests
+5. **Use conventional commits**: `npm run commit` for guided commits
+6. **Create a pull request**
+
+For complete details on commit formats, testing requirements, and MCP-specific development guidelines, see the [Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md).
+
+## Requirements
+
+- **Python**: 3.12+
+- **Dependencies**: `mcp>=1.6.0`
+- **Compatibility**: FastMCP servers and MCP clients
+
+## License
+
+AGPL v3: see [LICENSE](./LICENSE)
+
+---
+
+**Part of the [Cracking Shells Ecosystem](https://github.com/CrackingShells)**: [Hatch!](https://github.com/CrackingShells/Hatch) - A package management system for scientific MCP servers.