beads-mcp 0.9.4__tar.gz

beads_mcp-0.9.4/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+build/
+dist/
+wheels/
+*.egg-info
+__pycache__
+
+# Virtual environments
+.venv
+/.env
+/CLAUDE.md
+/TODO.md
+/.coverage

beads_mcp-0.9.4/.python-version

@@ -0,0 +1 @@
+3.13

beads_mcp-0.9.4/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.

beads_mcp-0.9.4/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: beads-mcp
+Version: 0.9.4
+Summary: MCP server for beads issue tracker.
+Project-URL: Homepage, https://github.com/steveyegge/beads
+Project-URL: Repository, https://github.com/steveyegge/beads
+Project-URL: Documentation, https://github.com/steveyegge/beads/blob/main/integrations/beads-mcp/README.md
+Project-URL: Issues, https://github.com/steveyegge/beads/issues
+Author: Beads Contributors
+Maintainer: Beads Contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai-agent,beads,claude,issue-tracker,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Bug Tracking
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastmcp==2.12.4
+Requires-Dist: pydantic-settings==2.11.0
+Requires-Dist: pydantic==2.12.0
+Description-Content-Type: text/markdown
+
+# beads-mcp
+
+MCP server for [beads](https://github.com/steveyegge/beads) issue tracker and agentic memory system.
+Enables AI agents to manage tasks using bd CLI through Model Context Protocol.
+
+## Installing
+
+```bash
+git clone https://github.com/steveyegge/beads
+cd beads/integrations/beads-mcp
+uv sync
+```
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "beads": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/beads-mcp",
+        "run",
+        "beads-mcp"
+      ],
+      "env": {
+        "BEADS_PATH": "/home/user/.local/bin/bd",
+      }
+    }
+  }
+}
+```
+
+**Environment Variables** (all optional):
+- `BEADS_PATH` - Path to bd executable (default: `~/.local/bin/bd`)
+- `BEADS_DB` - Path to beads database file (default: auto-discover from cwd)
+- `BEADS_ACTOR` - Actor name for audit trail (default: `$USER`)
+- `BEADS_NO_AUTO_FLUSH` - Disable automatic JSONL sync (default: `false`)
+- `BEADS_NO_AUTO_IMPORT` - Disable automatic JSONL import (default: `false`)
+
+## Features
+
+**Resource:**
+- `beads://quickstart` - Quickstart guide for using beads
+
+**Tools:**
+- `init` - Initialize bd in current directory
+- `create` - Create new issue (bug, feature, task, epic, chore)
+- `list` - List issues with filters (status, priority, type, assignee)
+- `ready` - Find tasks with no blockers ready to work on
+- `show` - Show detailed issue info including dependencies
+- `update` - Update issue (status, priority, design, notes, etc)
+- `close` - Close completed issue
+- `dep` - Add dependency (blocks, related, parent-child, discovered-from)
+- `blocked` - Get blocked issues
+- `stats` - Get project statistics
+
+
+## Development
+
+Run MCP inspector:
+```bash
+# inside beads-mcp dir
+uv run fastmcp dev src/beads_mcp/server.py
+```
+
+Type checking:
+```bash
+uv run mypy src/beads_mcp
+```
+
+Linting and formatting:
+```bash
+uv run ruff check src/beads_mcp
+uv run ruff format src/beads_mcp
+```
+
+## Testing
+
+Run all tests:
+```bash
+uv run pytest
+```
+
+With coverage:
+```bash
+uv run pytest --cov=beads_mcp tests/
+```
+
+Test suite includes both mocked unit tests and integration tests with real `bd` CLI.

beads_mcp-0.9.4/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/)

beads_mcp-0.9.4/README.md

@@ -0,0 +1,91 @@
+# beads-mcp
+
+MCP server for [beads](https://github.com/steveyegge/beads) issue tracker and agentic memory system.
+Enables AI agents to manage tasks using bd CLI through Model Context Protocol.
+
+## Installing
+
+```bash
+git clone https://github.com/steveyegge/beads
+cd beads/integrations/beads-mcp
+uv sync
+```
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "beads": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/beads-mcp",
+        "run",
+        "beads-mcp"
+      ],
+      "env": {
+        "BEADS_PATH": "/home/user/.local/bin/bd",
+      }
+    }
+  }
+}
+```
+
+**Environment Variables** (all optional):
+- `BEADS_PATH` - Path to bd executable (default: `~/.local/bin/bd`)
+- `BEADS_DB` - Path to beads database file (default: auto-discover from cwd)
+- `BEADS_ACTOR` - Actor name for audit trail (default: `$USER`)
+- `BEADS_NO_AUTO_FLUSH` - Disable automatic JSONL sync (default: `false`)
+- `BEADS_NO_AUTO_IMPORT` - Disable automatic JSONL import (default: `false`)
+
+## Features
+
+**Resource:**
+- `beads://quickstart` - Quickstart guide for using beads
+
+**Tools:**
+- `init` - Initialize bd in current directory
+- `create` - Create new issue (bug, feature, task, epic, chore)
+- `list` - List issues with filters (status, priority, type, assignee)
+- `ready` - Find tasks with no blockers ready to work on
+- `show` - Show detailed issue info including dependencies
+- `update` - Update issue (status, priority, design, notes, etc)
+- `close` - Close completed issue
+- `dep` - Add dependency (blocks, related, parent-child, discovered-from)
+- `blocked` - Get blocked issues
+- `stats` - Get project statistics
+
+
+## Development
+
+Run MCP inspector:
+```bash
+# inside beads-mcp dir
+uv run fastmcp dev src/beads_mcp/server.py
+```
+
+Type checking:
+```bash
+uv run mypy src/beads_mcp
+```
+
+Linting and formatting:
+```bash
+uv run ruff check src/beads_mcp
+uv run ruff format src/beads_mcp
+```
+
+## Testing
+
+Run all tests:
+```bash
+uv run pytest
+```
+
+With coverage:
+```bash
+uv run pytest --cov=beads_mcp tests/
+```
+
+Test suite includes both mocked unit tests and integration tests with real `bd` CLI.

beads_mcp-0.9.4/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "beads-mcp"
+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",
+    "pydantic-settings==2.11.0",
+]
+authors = [
+    {name = "Beads Contributors"}
+]
+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"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_unreachable = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 115
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "C4",
+]
+ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.18.2",
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.14.0",
+]

beads_mcp-0.9.4/src/beads_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""MCP Server for Beads Agentic Task Tracker and Memory System
+
+This package provides an MCP (Model Context Protocol) server that exposes
+beads (bd) issue tracker functionality to MCP Clients.
+"""
+
+__version__ = "0.9.4"

beads_mcp-0.9.4/src/beads_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running beads_mcp as a module."""
+
+from beads_mcp.server import main
+
+if __name__ == "__main__":
+    main()