Spaces:
Running
Running
| # Contributing to Universal MCP Hub | |
| Thanks for considering a contribution. Read this before opening a PR. | |
| --- | |
| ## Before You Start | |
| Open an issue first for anything non-trivial. Describe what you want to change and why. This avoids situations where you spend time on a PR that conflicts with the architecture or is out of scope. | |
| For typos, doc fixes, or obvious bugs — just open the PR directly. | |
| --- | |
| ## The Non-Negotiables | |
| These rules are not up for debate in PRs. If you disagree with them, open an issue and make the case. | |
| **1. Don't break the sandbox.** | |
| `app/*` must never import from `fundaments/`, read `os.environ`, or access `.env` directly. The Guardian pattern (`main.py` injects services, `app/*` receives them) is the core security guarantee of this project. PRs that route around it will be closed. | |
| **2. No secrets in code or config.** | |
| `app/.pyfun` references ENV variable names only — never values. If your PR puts an API key, token, or credential anywhere in the codebase, it gets closed immediately. | |
| **3. `db_query` stays SELECT-only.** | |
| The read-only enforcement in `db_sync.py` is not a suggestion. Don't submit PRs that add write access through the MCP tool layer. | |
| **4. New providers need a dummy too.** | |
| If you add a new LLM or search provider, add a commented-out dummy class following the existing pattern. Future contributors should be able to add the next provider by copying your dummy. | |
| --- | |
| ## How to Add a New LLM Provider | |
| Three files, nothing else: | |
| **1. `app/providers.py`** — add your class (copy the OpenAI dummy as starting point): | |
| ```python | |
| class YourProvider(BaseProvider): | |
| """Your Provider API — brief description.""" | |
| async def complete(self, prompt: str, model: str = None, max_tokens: int = 1024) -> str: | |
| data = await self._post( | |
| f"{self.base_url}/chat/completions", # adjust endpoint | |
| headers={ | |
| "Authorization": f"Bearer {self.key}", | |
| "content-type": "application/json", | |
| }, | |
| payload={ | |
| "model": model or self.model, | |
| "max_tokens": max_tokens, | |
| "messages": [{"role": "user", "content": prompt}], | |
| }, | |
| ) | |
| return data["choices"][0]["message"]["content"] # adjust response parsing | |
| ``` | |
| **2. `app/providers.py`** — register in `_PROVIDER_CLASSES`: | |
| ```python | |
| _PROVIDER_CLASSES = { | |
| ... | |
| "yourprovider": YourProvider, | |
| } | |
| ``` | |
| **3. `app/.pyfun`** — add provider block: | |
| ```ini | |
| [LLM_PROVIDER.yourprovider] | |
| active = "true" | |
| base_url = "https://api.yourprovider.com/v1" | |
| env_key = "YOUR_PROVIDER_API_KEY" | |
| default_model = "your-default-model" | |
| models = "your-default-model, other-model" | |
| fallback_to = "" | |
| [LLM_PROVIDER.yourprovider_END] | |
| ``` | |
| Then add a commented dummy of your class above the `_PROVIDER_CLASSES` dict with the `.pyfun` block as a comment — same style as OpenAI/Mistral/xAI dummies already there. | |
| Most OpenAI-compatible APIs (Mistral, xAI, Together, etc.) need zero changes to the class body — just different `base_url` and `env_key`. Providers with non-standard auth (like Gemini's `?key=` param) need their own `complete()` implementation. | |
| --- | |
| ## How to Add a New Search Provider | |
| Search providers follow the same pattern as LLM providers but register in `_SEARCH_REGISTRY` (not yet implemented — first search provider PR sets the pattern). Look at how `BraveProvider` and `TavilyProvider` are planned in `.pyfun` for reference. | |
| --- | |
| ## How to Add a New Tool | |
| Tools are defined in `app/.pyfun` under `[TOOLS]` and registered in `app/mcp.py`. A tool needs: | |
| - A `[TOOL.name]` block in `.pyfun` with `provider_type`, `default_provider`, `system_prompt` (for LLM tools) | |
| - Registration in `mcp.py` via the appropriate `_register_*_tools()` function | |
| - Execution logic in `app/tools.py` | |
| Tools that require an API key must gate their registration — if the key isn't set, the tool must not register. No key, no tool, no crash. See existing tool registration in `mcp.py` for the pattern. | |
| --- | |
| ## Code Style | |
| - Match the existing style — same header format, same section separators, same logging pattern | |
| - One logger per module: `logger = logging.getLogger("module_name")` | |
| - Async where the code is already async (`app/*`), sync where it's sync (`fundaments/*`) | |
| - Comments explain *why*, not *what* — the code shows what | |
| --- | |
| ## Testing Your Changes | |
| Before submitting: | |
| ```bash | |
| # install dependencies | |
| pip install -r requirements.txt | |
| # start with minimal config (no keys needed for basic startup test) | |
| python main.py | |
| # check that startup completes without errors | |
| # check that list_active_tools returns expected results | |
| # check that missing keys don't crash the server | |
| ``` | |
| If you're adding a provider: test with a real key in a local `.env`. Document the response format you're parsing from in your PR description. | |
| --- | |
| ## PR Checklist | |
| - [ ] Sandbox rules not broken (`app/*` has no new `os.environ` or `fundaments/` imports) | |
| - [ ] No credentials or secrets in any file | |
| - [ ] New provider includes dummy class + `.pyfun` block | |
| - [ ] Startup still works with zero API keys configured | |
| - [ ] Code follows existing style and header format | |
| - [ ] PR description explains what changed and why | |
| --- | |
| ## What Won't Be Merged | |
| - Features that add attack surface without clear security justification | |
| - AI-generated code the author can't explain in review | |
| - PRs that touch `fundaments/` without a very good reason — that layer is stable by design | |
| - Dependency additions without justification — the stack is intentionally lean | |
| --- | |
| *Questions? Open an issue. The architecture docs in `README.md`, `SECURITY.md`, and `docs/` cover most of the "why" behind the design decisions.* | |