Development Guide¶

This guide covers how to set up a development environment and contribute to Shepherd MCP.

Setup¶

Clone the repository:

git clone https://github.com/neuralis/shepherd-mcp
cd shepherd-mcp

Create a virtual environment and install dependencies:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

Running Tests¶

Run the test suite with pytest:

pytest

Run with coverage:

pytest --cov=shepherd_mcp

Running Locally¶

Set up your environment variables:

export AIOBS_API_KEY=aiobs_sk_xxxx
export LANGFUSE_PUBLIC_KEY=pk-lf-xxxx
export LANGFUSE_SECRET_KEY=sk-lf-xxxx

Run the MCP server:

python -m shepherd_mcp

Code Style¶

This project uses ruff for linting and formatting:

# Check for issues
ruff check .

# Auto-fix issues
ruff check --fix .

# Format code
ruff format .

Project Structure¶

src/shepherd_mcp/
├── __init__.py          # Package exports
├── __main__.py          # Entry point
├── server.py            # MCP server with tool handlers
├── models/              # Data models
│   ├── __init__.py
│   ├── aiobs.py         # AIOBS-specific models
│   └── langfuse.py      # Langfuse-specific models
└── providers/           # Provider clients
    ├── __init__.py
    ├── base.py          # Base provider interface
    ├── aiobs.py         # AIOBS client implementation
    └── langfuse.py      # Langfuse client implementation

Architecture¶

┌─────────────────┐     stdio      ┌─────────────────┐
│  Cursor/Claude  │ ◄────────────► │  shepherd-mcp   │
│    (Client)     │   stdin/stdout │   (subprocess)  │
└─────────────────┘                └────────┬────────┘
                                            │ HTTPS
                                  ┌─────────┴─────────┐
                                  │                   │
                                  ▼                   ▼
                         ┌─────────────┐     ┌─────────────┐
                         │ Shepherd API│     │ Langfuse API│
                         │   (AIOBS)   │     │   (Cloud)   │
                         └─────────────┘     └─────────────┘

Building Documentation¶

Build the Sphinx documentation:

cd docs
make html

The built documentation will be in docs/_build/html/.

Publishing to PyPI¶

Releases are automatically published to PyPI via GitHub Actions when a release is created.

To publish manually:

# Build the package
pip install build twine
python -m build

# Upload to PyPI
twine upload dist/*

Adding a New Provider¶

To add support for a new observability provider:

Create a new models file in src/shepherd_mcp/models/ with your data models
Create a new provider client in src/shepherd_mcp/providers/ inheriting from BaseProvider
Add tool definitions in server.py under list_tools()
Add tool handlers in server.py under call_tool()
Update the provider exports in providers/__init__.py
Add tests in tests/

Example provider skeleton:

from shepherd_mcp.providers.base import BaseProvider, AuthenticationError

class MyProvider(BaseProvider):
    def __init__(self, api_key: str | None = None):
        self.api_key = api_key or os.environ.get("MY_PROVIDER_API_KEY")
        if not self.api_key:
            raise AuthenticationError("No API key provided")
        # Initialize HTTP client, etc.

    @property
    def name(self) -> str:
        return "my_provider"

    def list_sessions(self):
        # Implement session listing
        pass

    def close(self) -> None:
        # Clean up resources
        pass

Contributing¶

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Make your changes
Run tests: pytest
Run linting: ruff check .
Commit your changes: git commit -am 'Add my feature'
Push to the branch: git push origin feature/my-feature
Create a Pull Request