docs: create Development-Conventions wiki page
@@ -0,0 +1,75 @@
|
|||||||
|
# 🛠️ Development Conventions
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
All MCP servers in this repo follow consistent conventions for maintainability, testability, and Roo Code compatibility.
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
mcp/<server-name>/
|
||||||
|
├── src/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ └── server.py ← FastMCP server entry point
|
||||||
|
├── tests/
|
||||||
|
│ └── test_server.py ← pytest test suite
|
||||||
|
├── pyproject.toml ← uv-managed dependencies
|
||||||
|
├── run.sh ← launch script
|
||||||
|
├── 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
|
||||||
|
|
||||||
|
**Always use `uv`** — never `pip` directly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
uv init mcp/my-server
|
||||||
|
cd mcp/my-server
|
||||||
|
uv add fastmcp httpx
|
||||||
|
uv sync
|
||||||
|
uv run pytest tests/ -v
|
||||||
|
```
|
||||||
|
|
||||||
|
## Commit Convention
|
||||||
|
|
||||||
|
Conventional Commits format:
|
||||||
|
|
||||||
|
```
|
||||||
|
feat: add webscraper_fetch_section tool
|
||||||
|
fix: handle ComfyUI timeout gracefully
|
||||||
|
docs: update README with AMD setup
|
||||||
|
test: add unit tests for generate_image
|
||||||
|
chore: bump fastmcp to 2.1.0
|
||||||
|
```
|
||||||
|
|
||||||
|
## Creating a New MCP Server
|
||||||
|
|
||||||
|
Use the `new-mcp-server` Roo skill in MCP Builder mode:
|
||||||
|
|
||||||
|
1. Switch to 🔧 MCP Builder mode in Roo Code
|
||||||
|
2. Say: "Create a new MCP server for `<purpose>`"
|
||||||
|
3. Roo loads the `new-mcp-server` skill and scaffolds everything
|
||||||
|
|
||||||
|
## Gitea Repository
|
||||||
|
|
||||||
|
Code at: `http://192.168.188.119:30008/pplate/pi_mcps`
|
||||||
|
|
||||||
|
Push with the `gitea-push` Roo skill for conventional commit format.
|
||||||
Reference in New Issue
Block a user