diff --git a/examples/claude-desktop-mcp/README.md b/examples/claude-desktop-mcp/README.md index 7c526ca7e..104fa6cec 100644 --- a/examples/claude-desktop-mcp/README.md +++ b/examples/claude-desktop-mcp/README.md @@ -1,18 +1,52 @@ # Claude Desktop MCP Server for Beads -> **Note**: This is a reference implementation showing how to integrate bd with Claude Desktop via MCP (Model Context Protocol). +> **Note**: The beads MCP server is now fully implemented! See [integrations/beads-mcp](../../integrations/beads-mcp/) for the production implementation. ## What This Provides -An MCP server that exposes bd functionality to Claude Desktop, allowing Claude to: +An MCP server that exposes bd functionality to Claude Desktop and other MCP clients, allowing Claude to: - Query ready work - Create and update issues - Manage dependencies - Track discovered work -## Implementation Status +## Quick Start -This is a **documentation stub** showing the intended integration pattern. Full implementation coming soon! +Install the beads MCP server: + +```bash +# Using uv (recommended) +uv tool install beads-mcp + +# Or using pip +pip install beads-mcp +``` + +Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): + +```json +{ + "mcpServers": { + "beads": { + "command": "beads-mcp" + } + } +} +``` + +Restart Claude Desktop and you're done! Claude can now manage your beads issues. + +## Full Documentation + +See the [beads-mcp README](../../integrations/beads-mcp/README.md) for: +- Installation instructions +- Configuration options +- Environment variables +- Development guide + +--- + +## Original Design Documentation (Historical) ## Planned Features diff --git a/integrations/beads-mcp/LICENSE b/integrations/beads-mcp/LICENSE new file mode 100644 index 000000000..2a187917a --- /dev/null +++ b/integrations/beads-mcp/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Beads Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/integrations/beads-mcp/PYPI.md b/integrations/beads-mcp/PYPI.md new file mode 100644 index 000000000..7dd4e1a88 --- /dev/null +++ b/integrations/beads-mcp/PYPI.md @@ -0,0 +1,179 @@ +# Publishing beads-mcp to PyPI + +This guide covers how to build and publish the beads-mcp package to the Python Package Index (PyPI). + +## Prerequisites + +1. **PyPI Account**: Create accounts on both: + - Test PyPI: https://test.pypi.org/account/register/ + - PyPI: https://pypi.org/account/register/ + +2. **API Tokens**: Generate API tokens for authentication: + - Test PyPI: https://test.pypi.org/manage/account/token/ + - PyPI: https://pypi.org/manage/account/token/ + +3. **Build Tools**: Install the Python build tools: + ```bash + uv pip install --upgrade build twine + ``` + +## Building the Package + +1. **Clean previous builds** (if any): + ```bash + rm -rf dist/ build/ src/*.egg-info + ``` + +2. **Build the distribution packages**: + ```bash + python -m build + ``` + + This creates both: + - `dist/beads_mcp-0.9.4-py3-none-any.whl` (wheel) + - `dist/beads-mcp-0.9.4.tar.gz` (source distribution) + +3. **Verify the build**: + ```bash + tar -tzf dist/beads-mcp-0.9.4.tar.gz + ``` + + Should include: + - Source files in `src/beads_mcp/` + - `README.md` + - `LICENSE` + - `pyproject.toml` + +## Testing the Package + +### Test on Test PyPI First + +1. **Upload to Test PyPI**: + ```bash + python -m twine upload --repository testpypi dist/* + ``` + + When prompted, use: + - Username: `__token__` + - Password: Your Test PyPI API token (including the `pypi-` prefix) + +2. **Install from Test PyPI**: + ```bash + # In a fresh virtual environment + uv venv test-env + source test-env/bin/activate + + # Install from Test PyPI + pip install --index-url https://test.pypi.org/simple/ beads-mcp + + # Test it works + beads-mcp --help + ``` + +3. **Verify the installation**: + ```bash + python -c "import beads_mcp; print(beads_mcp.__version__)" + ``` + +## Publishing to PyPI + +Once you've verified the package works on Test PyPI: + +1. **Upload to PyPI**: + ```bash + python -m twine upload dist/* + ``` + + Use: + - Username: `__token__` + - Password: Your PyPI API token + +2. **Verify on PyPI**: + - Visit https://pypi.org/project/beads-mcp/ + - Check that the README displays correctly + - Verify all metadata is correct + +3. **Test installation**: + ```bash + # In a fresh environment + pip install beads-mcp + beads-mcp --help + ``` + +## Updating the README Installation Instructions + +After publishing, users can install simply with: + +```bash +pip install beads-mcp +# or with uv +uv pip install beads-mcp +``` + +Update the README.md to reflect this simpler installation method. + +## Version Management + +When releasing a new version: + +1. Update version in `src/beads_mcp/__init__.py` +2. Update version in `pyproject.toml` +3. Use the version bump script from the parent project: + ```bash + cd ../.. + ./scripts/bump-version.sh 0.9.5 --commit + ``` +4. Create a git tag: + ```bash + git tag v0.9.5 + git push origin v0.9.5 + ``` +5. Clean, rebuild, and republish to PyPI + +## Troubleshooting + +### Package Already Exists + +PyPI doesn't allow re-uploading the same version. If you need to fix something: +1. Increment the version number (even for minor fixes) +2. Rebuild and re-upload + +### Missing Files in Distribution + +If files are missing from the built package, create a `MANIFEST.in`: +``` +include README.md +include LICENSE +recursive-include src/beads_mcp *.py +``` + +### Authentication Errors + +- Ensure you're using `__token__` as the username (exactly) +- Token should include the `pypi-` prefix +- Check token hasn't expired + +### Test PyPI vs Production + +Test PyPI is completely separate from production PyPI: +- Different accounts +- Different tokens +- Different package versions (can have different versions on each) + +Always test on Test PyPI first! + +## Continuous Deployment (Future) + +Consider setting up GitHub Actions to automate this: +1. On tag push (e.g., `v0.9.5`) +2. Run tests +3. Build package +4. Publish to PyPI + +See `.github/workflows/` in the parent project for examples. + +## Resources + +- [Python Packaging Guide](https://packaging.python.org/tutorials/packaging-projects/) +- [PyPI Documentation](https://pypi.org/help/) +- [Twine Documentation](https://twine.readthedocs.io/) diff --git a/integrations/beads-mcp/README.md b/integrations/beads-mcp/README.md index bde670abc..2d7ea24fb 100644 --- a/integrations/beads-mcp/README.md +++ b/integrations/beads-mcp/README.md @@ -5,13 +5,39 @@ Enables AI agents to manage tasks using bd CLI through Model Context Protocol. ## Installing +Install from PyPI: + +```bash +# Using uv (recommended) +uv tool install beads-mcp + +# Or using pip +pip install beads-mcp +``` + +Add to your Claude Desktop config: + +```json +{ + "mcpServers": { + "beads": { + "command": "beads-mcp" + } + } +} +``` + +### Development Installation + +For development, clone the repository: + ```bash git clone https://github.com/steveyegge/beads cd beads/integrations/beads-mcp uv sync ``` -Add to your Claude Desktop config: +Then use in Claude Desktop config: ```json { @@ -23,10 +49,7 @@ Add to your Claude Desktop config: "/path/to/beads-mcp", "run", "beads-mcp" - ], - "env": { - "BEADS_PATH": "/home/user/.local/bin/bd", - } + ] } } } diff --git a/integrations/beads-mcp/pyproject.toml b/integrations/beads-mcp/pyproject.toml index 391b7ee07..d0e7e4f6a 100644 --- a/integrations/beads-mcp/pyproject.toml +++ b/integrations/beads-mcp/pyproject.toml @@ -4,6 +4,7 @@ version = "0.9.4" description = "MCP server for beads issue tracker." readme = "README.md" requires-python = ">=3.11" +license = {text = "MIT"} dependencies = [ "fastmcp==2.12.4", "pydantic==2.12.0", @@ -12,16 +13,28 @@ dependencies = [ authors = [ {name = "Beads Contributors"} ] -keywords = ["beads", "mcp", "claude", "issue-tracker", "ai-agent"] +maintainers = [ + {name = "Beads Contributors"} +] +keywords = ["beads", "mcp", "claude", "issue-tracker", "ai-agent", "model-context-protocol"] classifiers = [ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", + "Topic :: Software Development :: Libraries :: Python Modules", + "Topic :: Software Development :: Bug Tracking", ] +[project.urls] +Homepage = "https://github.com/steveyegge/beads" +Repository = "https://github.com/steveyegge/beads" +Documentation = "https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/README.md" +Issues = "https://github.com/steveyegge/beads/issues" + [project.scripts] beads-mcp = "beads_mcp.server:main"