# Uploaded MCP Server Requirements This file is read by the LLM-assisted MCP install preflight. Treat it as the contract for making an uploaded server work with the Nemoclaw MCP broker. ## Runtime Contract - Uploaded MCP servers must expose a valid Model Context Protocol server. - Stdio servers must start from the configured command and args, speak MCP over stdin/stdout, initialize cleanly, and respond to tool discovery. - HTTP servers must expose a streamable HTTP MCP endpoint. Do not convert an uploaded stdio server into an HTTP server unless the project already clearly supports it. - The server must not require an interactive terminal, browser login flow, or long-running manual setup during launch. - Startup logs must go to stderr, not stdout, so stdout remains available for stdio MCP messages. - Secrets must be passed through env vars or server-side headers, never embedded in files, args, generated client handoffs, or logs. ## Broker Expectations - The broker launches local stdio servers on the controller host using the stored command, args, env, and working project files. - The broker validates a server by initializing it through the official MCP SDK and listing tools. - A server with zero tools can pass only if that is expected and clearly explained; otherwise treat zero tools as a warning that may indicate a broken entrypoint. - The broker must not expose launch commands, env vars, headers, or secrets to sandboxes. Sandboxes receive only broker access instructions. ## Python Uploads - Create and use a per-server virtual environment inside the uploaded project root at `.venv`. - Install `requirements.txt` with `.venv/bin/pip install -r requirements.txt` when present. - Install `pyproject.toml` projects with `.venv/bin/pip install -e .` when present. - Prefer the installed console script or `python -m package.module` when direct file execution causes package-relative import failures. - Use `.venv/bin/python` for Python file or module launches after dependency bootstrap. - Do not install Python dependencies globally. ## Node Uploads - If `package-lock.json` is present, use `npm ci`. - If only `package.json` is present, use `npm install`. - Use `node` for JavaScript entry files unless the package provides a documented executable script. - Do not require global npm installs for uploaded servers. ## Safe Repair Rules - Only inspect and modify files inside the uploaded MCP server directory. - Do not delete unrelated files. - Do not edit generated dependency directories such as `.venv`, `node_modules`, `dist`, `build`, or `__pycache__`. - Keep changes minimal and explain every changed file. - If a required dependency, credential, external service, or runtime is missing and cannot be inferred safely, report the failure and describe what the user must provide. ## Preflight Output A successful preflight should produce: - The final command and args the broker should launch. - Any env keys required, without secret values. - Dependency bootstrap logs or a note that no bootstrap was required. - MCP initialization and tool discovery result. - A concise summary of any fixes applied. A failed preflight should produce: - The observed failure. - Likely causes. - Suggested fixes. - Whether LLM-assisted repair can reasonably attempt a fix.