Metadata-Version: 2.4
Name: miadi-webweave-mcp
Version: 0.3.1
Summary: MCP server for miadi-webweave - Terminal-to-AI communication with A2A session management
Author-email: Mia Isabelle <mia@example.com>, gerico1007 <gerico@jgwill.com>
License: MIT
Project-URL: Homepage, https://github.com/miadisabelle/simexp
Project-URL: Documentation, https://github.com/miadisabelle/simexp/tree/main/miadi_webweave_mcp
Project-URL: Repository, https://github.com/miadisabelle/simexp.git
Project-URL: Issues, https://github.com/miadisabelle/simexp/issues
Keywords: mcp,simplenote,ai,a2a,session,browser-automation,claude
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: miadi-webweave>=0.7.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"

# MIA Miadi Webweave MCP

An MCP (Model Context Protocol) server that exposes all MIA Miadi Webweave functionality for use with Claude and other AI agents.

## Installation

Install from PyPI:

```bash
pip install miadi-webweave-mcp
```

Or install with development dependencies:

```bash
pip install miadi-webweave-mcp[dev]
```

## Quick Start

Start the MCP server:

```bash
miadi-webweave-mcp
```

The server will start listening for MCP protocol connections.

### Using with Claude CLI

Configure Claude to use the MIA Miadi Webweave MCP server:

```bash
# Create an MCP config file
cat > miadi-webweave-mcp.json << 'EOF'
{
  "mcpServers": {
    "miadi-webweave": {
      "command": "python",
      "args": ["-m", "miadi_webweave_mcp.server"]
    }
  }
}
EOF

# Run Claude with the MCP server
claude --mcp-config miadi-webweave-mcp.json -p "List all available webweave tools"
```

## Features

### Session Management Tools
- **webweave_session_start** - Start a new session with optional file/AI/issue/repo/profile/intention
- **webweave_session_list** - List all sessions in tree format
- **webweave_session_info** - Show current session & directory context
- **webweave_session_clear** - Clear active session
- **webweave_session_write** - Write message with optional timestamp (date) and prepend option
- **webweave_session_read** - Read session note content
- **webweave_session_add** - Add file with heading and direction classification
- **webweave_session_title** - Set session note title
- **webweave_session_open** - Open session note in browser
- **webweave_session_url** - Print session note URL

### Browser/CDP Profile Tools
- **webweave_browser_profiles** - List all CDP profiles with status
- **webweave_browser_launch** - Launch Chrome with CDP for a profile
- **webweave_browser_stop** - Stop Chrome CDP for a profile
- **webweave_browser_profile_add** - Add a new CDP profile

### Collaboration Tools
- **webweave_session_collab** - Share with Assembly (♠, 🌿, 🎸, 🧵)
- **webweave_session_collab_add** - Add collaborator by email
- **webweave_session_collab_list** - List all collaborators
- **webweave_session_publish** - Publish note (get public URL)

### Reflection & Wisdom Tools (Four Directions)
- **webweave_session_reflect** - Open editor for reflection notes
- **webweave_session_observe_pattern** - Record an observed pattern
- **webweave_session_extract_wisdom** - Extract and record wisdom
- **webweave_session_complete** - Complete session with ceremony

### A2A Communication (mia-anemoi)
- **webweave_send_message** - Send message to agent network
- **webweave_wait_for_mentions** - Wait for messages mentioning agent
- **webweave_list_agents** - List known agents
- **webweave_broadcast** - Broadcast message to all agents

### Session Continuations
- **webweave_session_fork** - Fork current session
- **webweave_session_genealogy** - Show session genealogy
- **webweave_create_checkpoint** - Create checkpoint
- **webweave_list_checkpoints** - List checkpoints
- **webweave_get_continuation** - Get continuation state

### Core Simplenote Tools
- **webweave_init** - Initialize session with browser authentication
- **webweave_write** - Write content to Simplenote note (with profile support)
- **webweave_read** - Read content from Simplenote note (with profile support, accepts session IDs)
- **webweave_session_browser** - Launch browser for authentication

**Total: 35 MCP tools**

## Authentication

Miadi Webweave MCP requires Simplenote credentials. When you first use the `webweave_init` tool, it will:

1. Detect that you don't have an active session
2. Launch your browser to Simplenote login page
3. Prompt you to log in manually
4. Persist the session for subsequent tool calls

Once authenticated, all subsequent tools can access your Simplenote data.

## Architecture

### Package Structure

```
miadi_webweave_mcp/
├── miadi_webweave_mcp/
│   ├── __init__.py       # Package initialization
│   ├── server.py         # MCP server and tool handlers
│   └── tools.py          # Tool implementations
├── tests/                # Test suite
├── pyproject.toml        # Modern Python packaging
├── Makefile              # Build automation
└── release.sh            # Release automation
```

### Main Components

**server.py** - MCP protocol server that:
- Handles all MCP protocol messages
- Routes tool calls to appropriate handlers
- Manages resource and prompt endpoints

**tools.py** - All tool implementations that:
- Wrap Miadi Webweave CLI commands
- Provide user-friendly MCP interfaces
- Handle input validation and error reporting

## Development

### Install for Development

```bash
cd miadi_webweave_mcp
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Build Distribution

```bash
make clean
make build
```

### Release Workflow

```bash
# Full test release
./release.sh

# Or use Makefile
make test-release  # Test PyPI
make upload        # Production PyPI
```

## Version Management

This package is versioned independently of the CLI it wraps — `pyproject.toml`
is the single source of truth for each.

```bash
make bump                # auto-increment patch version
./release.sh             # interactive release (build, tag, upload, push)
../release-all.sh        # coordinated release of both packages
```

`make build` / `make upload` run inside an isolated `../.release-venv`
toolchain rather than whatever `twine` happens to be on `PATH`. Run
`make tools` to provision and verify it.

## Configuration

Miadi Webweave MCP uses the parent `miadi-webweave` package configuration at
`~/.miadi/webweave/config.yaml`. See the main
[Miadi Webweave documentation](https://github.com/miadisabelle/simexp) for details.

## Troubleshooting

### "webweave_init must be called first"
The MCP server requires an active Simplenote session. Call `webweave_init` to authenticate:
```
→ webweave_init
← Opens browser for Simplenote login
```

### "Cannot find module mcp"
Ensure the `mcp` package is installed:
```bash
pip install mcp>=1.0.0
```

### Tests failing
Ensure all dependencies are installed and Python 3.10+ is available:
```bash
pip install -e ".[dev]"
python --version  # Should be 3.10+
```

## Contributing

Contributions welcome! Please ensure:
- All tests pass: `pytest`
- Code is formatted: `black .`
- Type hints are included

## License

MIT License - see LICENSE file for details

## Links

- **Main Package**: [Miadi Webweave on GitHub](https://github.com/miadisabelle/simexp)
- **Issue Tracking**: [Miadi Webweave Issues](https://github.com/miadisabelle/simexp/issues)
- **PyPI**: [miadi-webweave-mcp on PyPI](https://pypi.org/project/miadi-webweave-mcp/)

## Support

For issues, feature requests, or questions, please open an issue on the [main Miadi Webweave repository](https://github.com/miadisabelle/simexp/issues).
