{"id":30328564,"url":"https://github.com/stackloklabs/toolhive-actions","last_synced_at":"2025-08-19T03:02:28.277Z","repository":{"id":310055281,"uuid":"1036524426","full_name":"StacklokLabs/toolhive-actions","owner":"StacklokLabs","description":"A set of GitHub Actions for interacting with ToolHive","archived":false,"fork":false,"pushed_at":"2025-08-15T11:44:06.000Z","size":50,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-15T13:26:07.178Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StacklokLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.MD","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T07:47:17.000Z","updated_at":"2025-08-15T11:41:38.000Z","dependencies_parsed_at":"2025-08-15T13:26:13.544Z","dependency_job_id":"3b0785ed-821a-4b01-aba6-846a9d816501","html_url":"https://github.com/StacklokLabs/toolhive-actions","commit_stats":null,"previous_names":["stackloklabs/toolhive-actions"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/StacklokLabs/toolhive-actions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StacklokLabs","download_url":"https://codeload.github.com/StacklokLabs/toolhive-actions/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StacklokLabs%2Ftoolhive-actions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270928841,"owners_count":24669590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-18T01:07:31.058Z","updated_at":"2025-08-18T01:07:31.771Z","avatar_url":"https://github.com/StacklokLabs.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Toolhive GitHub Actions\n\n[![Test](https://github.com/StacklokLabs/toolhive-actions/actions/workflows/test.yml/badge.svg)](https://github.com/StacklokLabs/toolhive-actions/actions/workflows/test.yml)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nGitHub Actions for installing and running [Toolhive](https://github.com/stacklok/toolhive), a tool for managing Model Context Protocol (MCP) servers.\n\n## 🚀 Quick Start\n\n### Install Toolhive\n\n```yaml\n- name: Install Toolhive\n  uses: StacklokLabs/toolhive-actions/install@v0\n  with:\n    version: latest  # or specify a version like 'v0.2.5'\n```\n\n### Run an MCP Server\n\n```yaml\n- name: Run Fetch MCP Server\n  uses: stackloklabs/toolhive-actions/run-mcp-server@v0\n  with:\n    server: fetch\n```\n\n## 📦 Available Actions\n\n### 1. `install` - Install Toolhive CLI\n\nInstalls the Toolhive CLI (`thv`) on your GitHub Actions runner.\n\n**Features:**\n- 🔍 Auto-detects OS and architecture\n- 📌 Supports specific version installation\n- ✅ Checksum verification for security\n- 🚀 Caching for faster subsequent runs\n- 🖥️ Cross-platform support (Linux, macOS, Windows)\n\n[📖 Full Documentation](./install/README.md)\n\n### 2. `run-mcp-server` - Run MCP Servers\n\nRuns MCP servers using the installed Toolhive CLI.\n\n**Features:**\n- 📦 Run servers from Toolhive registry\n- 🐳 Support for Docker images\n- 🔧 Protocol schemes (uvx://, npx://, go://)\n- 🔐 Secret management\n- 📁 Volume mounting\n- 🌐 Network isolation\n- 🛠️ Tool filtering\n\n[📖 Full Documentation](./run-mcp-server/README.md)\n\n### 3. `mcp-config` - Save MCP Configuration\n\nPersists MCP server configurations to a file and optionally uploads as an artifact.\n\n**Features:**\n- 💾 Save MCP server configurations\n- 📤 Upload as GitHub Actions artifact\n- 🏷️ Filter servers by labels\n- 📊 JSON format output\n\n[📖 Full Documentation](./mcp-config/README.md)\n\n## 📚 Examples\n\n### Basic Installation and Usage\n\n```yaml\nname: Use Toolhive\non: [push]\n\njobs:\n  example:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Install Toolhive\n        uses: StacklokLabs/toolhive-actions/install@v0\n        \n      - name: Run Fetch Server\n        uses: StacklokLabs/toolhive-actions/run-mcp-server@v0\n        with:\n          server: fetch\n          \n      - name: Use the MCP Server\n        run: |\n          # Your code that uses the MCP server\n          echo \"Server is running at ${{ steps.run-server.outputs.url }}\"\n```\n\n### Advanced Usage with Secrets\n\n```yaml\n- name: Run GitHub MCP Server\n  uses: stackloklabs/toolhive-actions/run-mcp-server@v0\n  with:\n    server: github\n    secrets: |\n      {\n        \"GITHUB_PERSONAL_ACCESS_TOKEN\": \"${{ secrets.GITHUB_TOKEN }}\"\n      }\n```\n\n### Using Docker Images\n\n```yaml\n- name: Run Custom MCP Server\n  uses: StacklokLabs/toolhive-actions/run-mcp-server@v0\n  with:\n    server: my-org/my-mcp-server:latest\n    transport: sse\n    proxy-port: 8080\n```\n\n### Using Protocol Schemes\n\n```yaml\n- name: Run Python MCP Server\n  uses: stackloklabs/toolhive-actions/run-mcp-server@v0\n  with:\n    server: uvx://my-python-mcp-server@latest\n    volumes: |\n      ./data:/app/data\n```\n\n## 🎯 Use Cases\n\n- **AI-Powered CI/CD**: Integrate MCP servers into your workflows for AI-assisted tasks\n- **Documentation Generation**: Use MCP servers to generate or update documentation\n- **Code Analysis**: Run MCP servers for advanced code analysis and suggestions\n- **Testing**: Use MCP servers in your test suites for AI-powered testing\n- **Automation**: Automate complex tasks with MCP server capabilities\n\n## 🔧 Requirements\n\n- GitHub Actions runner (ubuntu-latest, macos-latest, or windows-latest)\n- Docker or Podman (for running MCP servers on Linux)\n- GitHub token (automatically provided in Actions)\n\n## 📊 Compatibility Matrix\n\n| Runner OS | Architecture | Install | Run Server | Notes |\n|-----------|-------------|---------|------------|-------|\n| Ubuntu    | amd64       | ✅      | ✅         | Fully supported |\n| Ubuntu    | arm64       | ✅      | ✅         | Fully supported |\n| macOS     | amd64       | ✅      | ⚠️         | See [#3](https://github.com/StacklokLabs/toolhive-actions/issues/3) |\n| macOS     | arm64       | ✅      | ⚠️         | See [#3](https://github.com/StacklokLabs/toolhive-actions/issues/3) |\n| Windows   | amd64       | ⚠️      | ✅         | See [#2](https://github.com/StacklokLabs/toolhive-actions/issues/2) |\n| Windows   | arm64       | ⚠️      | ✅         | See [#2](https://github.com/StacklokLabs/toolhive-actions/issues/2) |\n\n## ⚠️ Known Issues\n\n### Windows: PowerShell PATH Issue ([#2](https://github.com/StacklokLabs/toolhive-actions/issues/2))\nThe `thv` command may not be recognized in PowerShell after installation. **Workarounds:**\n- Use `shell: bash` in your workflow steps\n- Reference the full path: `${{ steps.install.outputs.path }}`\n\n### macOS: Container Runtime Not Available ([#3](https://github.com/StacklokLabs/toolhive-actions/issues/3))\nToolhive cannot run MCP servers on macOS runners due to missing container runtime. **Workarounds:**\n- Use Linux runners for running MCP servers\n- Use macOS only for installation testing\n\nFor the latest status and updates on these issues, please check the [issues page](https://github.com/StacklokLabs/toolhive-actions/issues).\n\n## 🔒 Security\n\n- All downloads are verified using checksums\n- Runs with minimal required permissions\n- Secrets are handled securely\n- Network isolation available for enhanced security\n\n## 📝 Versioning\n\nWe use semantic versioning and maintain major version tags:\n\n- `@v0` - Latest v0.x.x release (recommended for stability)\n- `@v0.0.2` - Specific version\n- `@main` - Latest development version (not recommended for production)\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/StacklokLabs/toolhive-actions.git\ncd toolhive-actions\n\n# Test the actions locally using act (https://github.com/nektos/act)\nact -W .github/workflows/test.yml\n\n# Or push to a branch and let GitHub Actions run the tests\ngit checkout -b test-branch\ngit push origin test-branch\n```\n\n### Testing in Your Own Workflow\n\nTo test these actions in your own repository:\n\n```yaml\nname: Test Toolhive Actions\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      \n      - name: Install Toolhive\n        uses: StacklokLabs/toolhive-actions/install@v0\n        \n      - name: Verify installation\n        run: thv version\n```\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🔗 Related Projects\n\n- [Toolhive](https://github.com/stacklok/toolhive) - The main Toolhive project\n- [Toolhive Documentation](https://docs.stacklok.com/toolhive) - Official documentation\n- [MCP Specification](https://modelcontextprotocol.io) - Model Context Protocol specification\n\n## 💬 Support\n\n- [GitHub Issues](https://github.com/StacklokLabs/toolhive-actions/issues) - Bug reports and feature requests\n- [Discord](https://discord.gg/stacklok) - Community support and discussions\n- [Documentation](https://docs.stacklok.com/toolhive) - Official Toolhive documentation\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackloklabs%2Ftoolhive-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackloklabs%2Ftoolhive-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackloklabs%2Ftoolhive-actions/lists"}