Skip to content

Latest commit

 

History

History
181 lines (120 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

181 lines (120 loc) · 4.82 KB

Contributing

We welcome all kinds of contributions - bug fixes, big features, docs, examples and more. You don't need to be an AI expert or even a Python developer to help out.

Checklist

Contributions are made through pull requests.

Before sending a pull request, make sure to do the following:

Please reach out to the mcp-agent maintainers before starting work on a large contribution. Get in touch at GitHub issues or on Discord.

Prerequisites

To build mcp-agent, you'll need the following installed:

  • Install uv, which we use for Python package management

  • Install Python >= 3.10. (You may already it installed. To see your version, use python -V at the command line.)

    If you don't, install it using uv python install 3.10

  • Install dev dependencies using:

    make sync

    This will sync all packages with extras and dev dependencies.

Development Commands

We provide a Makefile with common development commands:

Code Quality

Note: Lint and format are also run as part of the precommit hook defined in .pre-commit-config.yaml.

Format:

make format

Lint:

This autofixes linter errors as well:

make lint

Testing

Run tests:

make tests

Run tests with coverage:

make coverage

Generate HTML coverage report:

make coverage-report

Generate Schema

If you make changes to config.py, please also run the schema generator to update the mcp-agent.config.schema.json:

make schema

Scripts

There are several useful scripts in the scripts/ directory that can be invoked via uv run scripts/<script>.py [ARGS]

promptify.py

Generates prompt.md file for LLMs. Very helpful in leverage LLMs to help develop mcp-agent.

You can use the Makefile command for a quick generation with sensible defaults:

make prompt

Or run it directly with custom arguments:

uv run scripts/promptify.py -i "**/agents/**" -i "**/context.py" -x "**/app.py"

Use -i REGEX to include only specific files, and -x REGEX to exclude certain files.

Note: There's also an existing LLMS.txt file in the repository root that you can use directly as a prompt for LLMs.

Examples

We use the examples for end-to-end testing. We'd love for you to add Python unit tests for new functionality going forward.

At minimum, for any new feature or provider integration (e.g. additional LLM support), you should add example usage in the examples directory.

Running Examples

All examples are in the examples/ directory, organized by category (basic, mcp, usecases, etc.). Each example has its own README with specific instructions.

General pattern for running examples:

  1. Navigate to the example directory:

    cd examples/basic/mcp_basic_agent

  2. Install dependencies:

    uv pip install -r requirements.txt

  3. Configure secrets (if needed):

    cp mcp_agent.secrets.yaml.example mcp_agent.secrets.yaml
# Edit mcp_agent.secrets.yaml with your API keys

  4. Run the example:

    uv run main.py

Quick Examples:

  • Basic Agent (examples/basic/mcp_basic_agent/) - A "finder" agent with filesystem and fetch capabilities
  • Researcher (examples/usecases/mcp_researcher/) - Research assistant with search, web fetch, and Python interpreter

Each example includes a README explaining its purpose, architecture, and specific setup requirements.

Editor settings

If you use vscode, you might find the following settings.json useful. We've added them to the .vscode directory along with recommended extensions

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.rulers": []
  },
  "yaml.schemas": {
    "https://raw.githubusercontent.com/lastmile-ai/mcp-agent/main/schema/mcp-agent.config.schema.json": [
      "mcp-agent.config.yaml",
      "mcp_agent.config.yaml",
      "mcp-agent.secrets.yaml",
      "mcp_agent.secrets.yaml"
    ]
  }
}

Thank you

If you are considering contributing, or have already done so, thank you. This project is meant to streamline AI application development, and we need all the help we can get! Happy building.