diff --git a/Development-Conventions.-.md b/Development-Conventions.-.md new file mode 100644 index 0000000..3a5eb8a --- /dev/null +++ b/Development-Conventions.-.md @@ -0,0 +1,75 @@ +# 🛠️ Development Conventions + +![Dev Conventions Banner](http://192.168.188.119:30008/pplate/pi_mcps/raw/branch/main/docs/wiki/images/dev-conventions-banner.png) + +All MCP servers in this repo follow consistent conventions for maintainability, testability, and Roo Code compatibility. + +## Directory Structure + +``` +mcp// +├── 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 ``" +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.