Documentation Protocol for MCP Servers.md

Summary of Insights

1. Hugging Face Space Configuration is Critical: The initial "configuration error" was due to a missing metadata block in the README.md file. Hugging Face Spaces rely on this block to understand how to run the application. For Docker-based spaces, sdk: docker is essential.

2. Spaces Expect a Web Server: The "runtime error" occurred because the github-mcp-server application was designed to run as a command-line tool using stdio, not as a web service. Hugging Face Spaces require an application to listen for HTTP traffic on a specific port (usually 7860).

3. Wrapping stdio Applications: We solved the web server issue by "wrapping" the Go binary with a Python web server using FastAPI. This wrapper acts as a bridge, accepting HTTP requests and forwarding them to the stdio interface of the Go application.

4. Permissions and File System: We encountered permission errors when the application tried to write to directories it didn't have access to. In a containerized environment like Hugging Face Spaces, applications have restricted file system access. It's crucial to ensure that any file or directory creation happens in a writable location (like /data or /app).

5. Explicit Directory Creation: The application expected certain directories to exist before it started. We had to add mkdir -p commands to the startup script to create these directories explicitly, as the application wouldn't create them itself.

Protocol for Future MCP Server Setup

Here is a checklist you can follow to streamline the setup of similar servers on Hugging Face Spaces:

1. Initial Repository and Configuration Check:

• README.md: Ensure a README.md file exists. If not, create one.
• Metadata: Add the Hugging Face Space configuration block to the top of your README.md:

1 --- 2 title: [Your Server Name] 3 emoji: [🚀] 4 colorFrom: [blue] 5 colorTo: [green] 6 sdk: docker 7 ---

• Dockerfile: Check for an existing Dockerfile. This will be the primary file to modify.

2. Analyze the Application's Entry Point:

• In the Dockerfile, identify the ENTRYPOINT and CMD instructions.
• Determine if the application starts as a web server or a stdio command-line tool.
• If it's a web server, ensure it's configured to listen on 0.0.0.0:7860.
• If it's a stdio tool, proceed to the next step.

3. Implement a Web Server Wrapper (if needed):

• Create a requirements.txt file with the following content: 1 fastapi

2 uvicorn[standard]

• Create an app.py file with a Python web server to wrap the stdio application. You can use the one we created as a template.
• Update the Dockerfile:
  • Use a Python base image (e.g., FROM python:3.9-slim).
  • Copy the MCP server binary from the build stage (if applicable).
  • Copy the app.py and requirements.txt files.
  • Install the Python dependencies with RUN pip install --no-cache-dir -r requirements.txt.
  • Set the CMD to ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"].

4. Handle Permissions and Directories:

• If the application needs to write files, ensure the paths are in a writable directory (e.g., /data or /app).
• If the application fails because a directory is missing, add a RUN mkdir -p /path/to/your/dir command to the Dockerfile or a mkdir -p command to your startup script.

5. Commit and Push:

• Add all new and modified files to git (README.md, Dockerfile, app.py, requirements.txt).
• Commit with a clear message (e.g., "Configure for Hugging Face Spaces").
• Push the changes to your Hugging Face repository.

6. Debugging:

• Always check the container logs on the Hugging Face Space for errors.
• "Configuration error": Usually a problem with the README.md metadata.
• "Runtime error" / "Application not initialized": The application is not running as a web server on port 7860.
• "Permission denied": The application is trying to write to a restricted directory.
• "File not found": A file or directory is missing; it might need to be created in the Dockerfile or startup script.

By following this protocol, you should be able to set up new MCP servers on Hugging Face Spaces much more quickly and with fewer issues.