Skip to content

Commit 5ff45d3

Browse files
LittleCoinCoinLittleCoinCoin
authored
Merge pull request #4 from CrackingShells/dev
`semantic-release` & documentation
2 parents 1bed862 + 63bee0b commit 5ff45d3

19 files changed

Lines changed: 11435 additions & 3 deletions

File tree

‎.commitlintrc.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"extends": ["@commitlint/config-conventional"],
3+
"rules": {
4+
"type-enum": [
5+
2,
6+
"always",
7+
[
8+
"build",
9+
"chore",
10+
"ci",
11+
"docs",
12+
"feat",
13+
"fix",
14+
"perf",
15+
"refactor",
16+
"revert",
17+
"style",
18+
"test"
19+
]
20+
],
21+
"subject-case": [2, "never", ["start-case", "pascal-case", "upper-case"]],
22+
"subject-empty": [2, "never"],
23+
"subject-full-stop": [2, "never", "."],
24+
"header-max-length": [2, "always", 72],
25+
"body-max-line-length": [2, "always", 500]
26+
}
27+
}

‎.github/workflows/commitlint.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: Commit Lint
2+
3+
on:
4+
pull_request:
5+
branches: [main, dev]
6+
7+
jobs:
8+
commitlint:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v4
13+
with:
14+
fetch-depth: 0
15+
16+
- name: Setup Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: "lts/*"
20+
21+
- name: Install dependencies
22+
run: npm ci
23+
24+
- name: Validate PR commits with commitlint
25+
run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

‎.github/workflows/semantic-release.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: Semantic Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- dev
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
18+
- name: Setup Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: '3.12'
22+
23+
- name: Install Python dependencies
24+
run: |
25+
python -m pip install --upgrade pip
26+
pip install -e .
27+
28+
- name: Run tests
29+
run: |
30+
python -c "import hatch_mcp_server; print('Package imports successfully')"
31+
32+
release:
33+
needs: test
34+
runs-on: ubuntu-latest
35+
if: github.event_name == 'push'
36+
steps:
37+
- name: Generate GitHub App Token
38+
id: generate_token
39+
uses: tibdex/github-app-token@v2
40+
with:
41+
app_id: ${{ secrets.SEMANTIC_RELEASE_APP_ID }}
42+
private_key: ${{ secrets.SEMANTIC_RELEASE_PRIVATE_KEY }}
43+
44+
- name: Checkout
45+
uses: actions/checkout@v4
46+
with:
47+
fetch-depth: 0
48+
token: ${{ steps.generate_token.outputs.token }}
49+
50+
- name: Setup Node.js
51+
uses: actions/setup-node@v4
52+
with:
53+
node-version: "lts/*"
54+
55+
- name: Install Node dependencies
56+
run: npm ci
57+
58+
- name: Verify npm audit
59+
run: npm audit signatures
60+
61+
- name: Release
62+
env:
63+
GITHUB_TOKEN: ${{ steps.generate_token.outputs.token }}
64+
run: npx semantic-release

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,3 +205,12 @@ cython_debug/
205205
marimo/_static/
206206
marimo/_lsp/
207207
__marimo__/
208+
209+
# Node.js dependencies for semantic-release
210+
node_modules/
211+
npm-debug.log*
212+
yarn-debug.log*
213+
yarn-error.log*
214+
215+
# Semantic-release
216+
.semantic-release/

‎.releaserc.json‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
{
2+
"repositoryUrl": "https://github.com/CrackingShells/Hatch-MCP-Server",
3+
"tagFormat": "v${version}",
4+
"branches": [
5+
"main",
6+
{
7+
"name": "dev",
8+
"prerelease": "dev"
9+
}
10+
],
11+
"plugins": [
12+
[
13+
"@semantic-release/commit-analyzer",
14+
{
15+
"preset": "conventionalcommits",
16+
"releaseRules": [
17+
{"type": "docs", "scope": "README", "release": "patch"},
18+
{"type": "refactor", "release": "patch"},
19+
{"type": "style", "release": "patch"},
20+
{"type": "test", "release": false},
21+
{"type": "chore", "release": false}
22+
]
23+
}
24+
],
25+
[
26+
"@semantic-release/release-notes-generator",
27+
{
28+
"preset": "conventionalcommits",
29+
"presetConfig": {
30+
"types": [
31+
{"type": "feat", "section": "Features"},
32+
{"type": "fix", "section": "Bug Fixes"},
33+
{"type": "docs", "section": "Documentation"},
34+
{"type": "refactor", "section": "Code Refactoring"},
35+
{"type": "perf", "section": "Performance Improvements"}
36+
]
37+
}
38+
}
39+
],
40+
[
41+
"@semantic-release/changelog",
42+
{
43+
"changelogFile": "CHANGELOG.md"
44+
}
45+
],
46+
[
47+
"@semantic-release/git",
48+
{
49+
"assets": ["CHANGELOG.md", "pyproject.toml"],
50+
"message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
51+
}
52+
],
53+
[
54+
"@semantic-release/github",
55+
{
56+
"successComment": false,
57+
"failComment": false,
58+
"releasedLabels": false
59+
}
60+
]
61+
]
62+
}

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
## [0.3.0-dev.1](https://github.com/CrackingShells/Hatch-MCP-Server/compare/v0.2.0...v0.3.0-dev.1) (2025-09-06)
2+
3+
4+
### Features
5+
6+
* migrate to semantic-release ([b8f8673](https://github.com/CrackingShells/Hatch-MCP-Server/commit/b8f867341f893a66688fedcf8231b4bf8ba674f0))
7+
8+
9+
### Documentation
10+
11+
* first pass on documentation ([4a283b3](https://github.com/CrackingShells/Hatch-MCP-Server/commit/4a283b39e7d1f74d8a832f492093b026da0e03cd))

‎README.md‎

Lines changed: 173 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,174 @@
11
# Hatch-MCP-Server
2-
The wrapper around MCP server for Hatch-related applications
2+
3+
A wrapper around FastMCP servers that adds automatic citation capabilities for scientific transparency and attribution in MCP (Model Context Protocol) applications.
4+
5+
## What is HatchMCP?
6+
7+
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.
8+
9+
**Key Features:**
10+
11+
- 🔬 **Scientific Attribution**: Automatic citation resource registration
12+
- 🔄 **FastMCP Compatibility**: Works with existing FastMCP servers
13+
- 📋 **Standardized URIs**: Uses `citation://origin/` and `citation://mcp/` schemes
14+
- 🪶 **Lightweight**: Minimal overhead, zero configuration required
15+
16+
## Quick Start
17+
18+
### Installation
19+
20+
```bash
21+
# Install directly from the repository
22+
pip install git+https://github.com/CrackingShells/Hatch-MCP-Server.git
23+
24+
# Or install local copy
25+
git clone https://github.com/CrackingShells/Hatch-MCP-Server.git
26+
cd Hatch-MCP-Server
27+
pip install .
28+
```
29+
30+
### Basic Usage
31+
32+
```python
33+
from hatch_mcp_server import HatchMCP
34+
35+
# Create an MCP server with citation capabilities
36+
hatch_mcp = HatchMCP(
37+
name="MyServer",
38+
origin_citation="Smith, J. 'Original Algorithm', Nature, 2024",
39+
mcp_citation="Your Name, 'MCP Implementation', GitHub, 2024"
40+
)
41+
42+
# Add tools using FastMCP decorator syntax
43+
@hatch_mcp.server.tool()
44+
def process_data(data: str) -> str:
45+
"""Process data using the wrapped algorithm."""
46+
hatch_mcp.logger.info(f"Processing: {data}")
47+
return f"Processed: {data}"
48+
49+
# Run the server
50+
if __name__ == "__main__":
51+
hatch_mcp.server.run()
52+
```
53+
54+
### Existing FastMCP Server
55+
56+
Assuming you have an existing FastMCP server (`mcp_server.py`)
57+
58+
```python
59+
from mcp.server.fastmcp import FastMCP
60+
61+
existing_server = FastMCP("my_existing_server")
62+
63+
@existing_server.tool()
64+
def existing_function(data: str) -> str:
65+
return f"Existing: {data}"
66+
```
67+
68+
You can wrap it with HatchMCP:
69+
70+
```python
71+
from mcp.server.fastmcp import FastMCP
72+
from hatch_mcp_server import HatchMCP
73+
74+
from mcp_server import existing_server
75+
76+
# Wrap with HatchMCP for citation capabilities
77+
hatch_mcp = HatchMCP(
78+
name="my_existing_server",
79+
fast_mcp=existing_server,
80+
origin_citation="Original work citation",
81+
mcp_citation="MCP implementation citation"
82+
)
83+
84+
# Run the server
85+
if __name__ == "__main__":
86+
hatch_mcp.server.run()
87+
```
88+
89+
The server automatically exposes citation information through:
90+
91+
- `citation://origin/MyServer` - Original algorithm citation
92+
- `citation://mcp/MyServer` - MCP implementation citation
93+
94+
## Documentation
95+
96+
📚 **[Complete Documentation](docs/articles/index.md)** - Full documentation table of contents and navigation guide
97+
98+
### Quick Start Guides
99+
100+
- **[Getting Started](docs/articles/users/GettingStarted.md)** - Installation, setup, and first steps
101+
- **[API Reference](docs/articles/users/APIReference.md)** - Complete API documentation
102+
- **[Citation System](docs/articles/users/CitationSystem.md)** - Understanding scientific attribution features
103+
- **[Examples](docs/articles/users/Examples.md)** - Practical usage patterns and code samples
104+
105+
### Developer Resources
106+
107+
- **[Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md)** - Complete development workflow and MCP-specific requirements
108+
- **[Architecture Overview](docs/articles/devs/architecture/Overview.md)** - Design principles and implementation details
109+
110+
### I Want To
111+
112+
- **🚀 Get started quickly** → [Installation & Quick Start](docs/articles/users/GettingStarted.md#installation)
113+
- **🔄 Wrap existing FastMCP servers** → [Basic Usage](docs/articles/users/GettingStarted.md#Wrapping-Existing-FastMCP-Servers)
114+
- **📖 Learn about citations** → [Citation System Guide](docs/articles/users/CitationSystem.md)
115+
- **🔍 Look up specific APIs** → [API Reference](docs/articles/users/APIReference.md)
116+
- **💡 See examples** → [Examples & Patterns](docs/articles/users/Examples.md)
117+
- **🛠️ Contribute code** → [Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md)
118+
- **🏗️ Understand design** → [Architecture Overview](docs/articles/devs/architecture/Overview.md)
119+
- **📋 Browse all docs** → [Documentation Table of Contents](docs/articles/index.md)
120+
121+
## Why Use HatchMCP?
122+
123+
### Scientific Transparency
124+
125+
```python
126+
# Citation information is automatically available to MCP clients
127+
# citation://origin/ServerName -> "Smith, J. 'Algorithm X', Nature, 2024"
128+
# citation://mcp/ServerName -> "Your Name, 'MCP Implementation', 2024"
129+
```
130+
131+
### Zero Configuration
132+
133+
```python
134+
# Just wrap your server - citation resources are registered automatically
135+
hatch_mcp = HatchMCP("server_name", origin_citation="...", mcp_citation="...")
136+
# Use hatch_mcp.server exactly like FastMCP
137+
```
138+
139+
### FastMCP Compatibility
140+
141+
```python
142+
# Wrap existing FastMCP servers without changes
143+
existing_server = FastMCP("my_server")
144+
wrapped = HatchMCP("my_server", fast_mcp=existing_server, ...)
145+
```
146+
147+
## Contributing
148+
149+
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.
150+
151+
### Overview
152+
153+
1. **Fork and clone** the repository
154+
2. **Install dependencies**: `pip install -e .` and `npm install`
155+
3. **Create a feature branch**: `git checkout -b feat/your-feature`
156+
4. **Make changes** and add tests
157+
5. **Use conventional commits**: `npm run commit` for guided commits
158+
6. **Create a pull request**
159+
160+
For complete details on commit formats, testing requirements, and MCP-specific development guidelines, see the [Contributing Guide](docs/articles/devs/contribution_guidelines/Contributing.md).
161+
162+
## Requirements
163+
164+
- **Python**: 3.12+
165+
- **Dependencies**: `mcp>=1.6.0`
166+
- **Compatibility**: FastMCP servers and MCP clients
167+
168+
## License
169+
170+
AGPL v3: see [LICENSE](./LICENSE)
171+
172+
---
173+
174+
**Part of the [Cracking Shells Ecosystem](https://github.com/CrackingShells)**: [Hatch!](https://github.com/CrackingShells/Hatch) - A package management system for scientific MCP servers.

0 commit comments

Comments
 (0)