feat(mcp): Setup beads-mcp for PyPI distribution
Prepared the beads-mcp package for publishing to PyPI, simplifying installation for users who want to use the MCP server with Claude Desktop or other MCP clients. Changes: - Added LICENSE file (MIT) to integrations/beads-mcp/ - Updated pyproject.toml with PyPI metadata (license, URLs, classifiers) - Updated README with simplified installation (uv tool install beads-mcp) - Created PYPI.md with detailed publishing guide - Updated examples/claude-desktop-mcp/README to reference the production MCP server Installation is now simplified from: git clone && cd && uv sync to: uv tool install beads-mcp Configuration is simplified from multi-line with --directory args to: "command": "beads-mcp" Tested build successfully. Package ready for: - Test PyPI: python -m twine upload --repository testpypi dist/* - Production PyPI: python -m twine upload dist/* 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
@@ -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
|
||||
|
||||
|
||||
21
integrations/beads-mcp/LICENSE
Normal file
21
integrations/beads-mcp/LICENSE
Normal file
@@ -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.
|
||||
179
integrations/beads-mcp/PYPI.md
Normal file
179
integrations/beads-mcp/PYPI.md
Normal file
@@ -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/)
|
||||
@@ -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",
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
Reference in New Issue
Block a user