docs(wiki): migrate to git-based workflow with persistent wiki/ clone
- Extract all wiki content from create_wiki_pages.py into docs/wiki/pages/*.md - Add docs/wiki/deploy_wiki.sh: copies pages to wiki/ repo, commits, pushes - Add /wiki/ to .gitignore (anchored — does not affect docs/wiki/) - 12 pages: Home, MCP-Servers-Overview, mcp-image-gen, ComfyUI-Setup, mcp-webscraper (8 tools incl. search_hint), BigMind (schema v8), Development-Conventions, Java-Projects, Java-wellmann-shop, Java-mss-failsafe, Java-Architecture, _Sidebar - Workflow: edit docs/wiki/pages/*.md → ./docs/wiki/deploy_wiki.sh
This commit is contained in:
Patrick Plate
@@ -0,0 +1,152 @@
|
||||
# 🛠️ Development Conventions
|
||||
|
||||
|
||||
|
||||
All MCP servers in this repo follow a consistent set of conventions to ensure maintainability, testability, and compatibility with Roo Code tooling.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
Each MCP server lives at `mcp/<server-name>/` with this layout:
|
||||
|
||||
```
|
||||
mcp/<server-name>/
|
||||
├── src/
|
||||
│ ├── __init__.py
|
||||
│ └── server.py ← FastMCP server entry point
|
||||
├── tests/
|
||||
│ ├── conftest.py ← sys.path + shared fixtures
|
||||
│ └── test_server.py ← pytest test suite (100% mock coverage)
|
||||
├── pyproject.toml ← uv-managed dependencies
|
||||
├── README.md ← server documentation
|
||||
├── PLAN.md ← architecture plan (pre-implementation)
|
||||
└── ASSESSMENT.md ← pre-implementation assessment
|
||||
```
|
||||
|
||||
## FastMCP Pattern
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP("server-name")
|
||||
|
||||
@mcp.tool()
|
||||
def my_tool(param: str) -> str:
|
||||
"""Tool description shown to the AI."""
|
||||
return result
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp.run()
|
||||
```
|
||||
|
||||
## Package Management
|
||||
|
||||
**All projects use `uv`** — never `pip` directly:
|
||||
|
||||
```bash
|
||||
# Create new server
|
||||
uv init mcp/my-server
|
||||
cd mcp/my-server
|
||||
uv add fastmcp httpx
|
||||
|
||||
# Sync dependencies
|
||||
uv sync
|
||||
|
||||
# Run server
|
||||
uv run python src/server.py
|
||||
|
||||
# Run tests
|
||||
uv run pytest tests/ -v
|
||||
```
|
||||
|
||||
## pyproject.toml Template
|
||||
|
||||
```toml
|
||||
[project]
|
||||
name = "mcp-my-server"
|
||||
version = "0.1.0"
|
||||
requires-python = ">=3.11"
|
||||
dependencies = [
|
||||
"fastmcp>=2.0.0",
|
||||
"httpx",
|
||||
]
|
||||
|
||||
[project.optional-dependencies]
|
||||
test = ["pytest", "pytest-mock", "pytest-cov"]
|
||||
|
||||
[build-system]
|
||||
requires = ["hatchling"]
|
||||
build-backend = "hatchling.build"
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
```
|
||||
|
||||
## Testing Conventions
|
||||
|
||||
- Tests live in `tests/test_server.py`
|
||||
- `conftest.py` sets `sys.path` so imports work without install
|
||||
- Use `pytest` via `uv run pytest`
|
||||
- Mock **all** external calls (HTTP, filesystem, subprocess) with `pytest-mock` or `respx`
|
||||
- `monkeypatch` for env vars and module-level state
|
||||
- Aim for 100% tool function coverage
|
||||
- All tests must pass before committing
|
||||
|
||||
## Branching Strategy
|
||||
|
||||
**Never commit to main directly.**
|
||||
|
||||
```
|
||||
Branch format: type/scope/short-description
|
||||
|
||||
Types: feat / fix / docs / chore / spike
|
||||
Scopes: bigmind / webscraper / cannamanage / workshop / roo / plans / homelab
|
||||
|
||||
Examples:
|
||||
feat/mcp/new-gitea-server
|
||||
fix/bigmind/achievement-card-images
|
||||
docs/wiki/update-conventions
|
||||
chore/roo/update-mcp-json
|
||||
```
|
||||
|
||||
Merge to main with `--no-ff` after push to Gitea.
|
||||
|
||||
## Commit Convention
|
||||
|
||||
Follow **Conventional Commits** format:
|
||||
|
||||
```
|
||||
feat(mcp-webscraper): add webscraper_search_hint tool using Brave Search
|
||||
fix(bigmind): achievement card images missing background-image CSS
|
||||
docs(wiki): add Java projects pages
|
||||
test(mcp-image-gen): add edge case tests for generate_image
|
||||
refactor(bigmind): extract profile builder to separate module
|
||||
chore(roo): update mcp.json with new server entry
|
||||
```
|
||||
|
||||
## Wiki Update Workflow
|
||||
|
||||
Wiki pages live as real Markdown files in `docs/wiki/pages/`. To update and deploy:
|
||||
|
||||
```bash
|
||||
# 1. Edit the .md files in docs/wiki/pages/
|
||||
# 2. Deploy to Gitea wiki git repo:
|
||||
./docs/wiki/deploy_wiki.sh
|
||||
```
|
||||
|
||||
The deploy script clones the wiki git repo (`pi_mcps.wiki.git`), syncs all `.md` files, and pushes.
|
||||
|
||||
## Creating a New MCP Server
|
||||
|
||||
Use the `new-mcp-server` Roo skill in MCP Builder mode for full scaffolding:
|
||||
|
||||
```
|
||||
1. Switch to 🔧 MCP Builder mode in Roo Code
|
||||
2. Say: "Create a new MCP server for <purpose>"
|
||||
3. Roo will load the new-mcp-server skill and scaffold everything
|
||||
```
|
||||
|
||||
## Gitea Repository
|
||||
|
||||
Code is hosted at: `http://192.168.188.119:30008/pplate/pi_mcps`
|
||||
|
||||
Push with the `gitea-push` Roo skill to ensure conventional commit format and correct branch workflow.
|
||||
Reference in New Issue
Block a user