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