# Clink MCP Server (Python) - Development Guide
This is the Python MCP server for Clink, published to PyPI as `clink-mcp-server`.
## Source Location
This code lives in the voxos monorepo at `projects/clink/mcp-python/` and is published to:
- **GitHub:** https://github.com/Voxos-ai-Inc/clink-mcp-server-python
- **PyPI:** https://pypi.org/project/clink-mcp-server/
## Publishing to GitHub
This directory is synced to GitHub using git subtree. The GitHub repo is a mirror of this subdirectory.
### First-time setup
```bash
# Add the GitHub remote
git remote add github-mcp-python git@github.com:Voxos-ai-Inc/clink-mcp-server-python.git
```
### Publishing changes
After making changes to `projects/clink/mcp-python/`:
```bash
# 1. Commit your changes to the monorepo
git add projects/clink/mcp-python/
git commit -m "feat(mcp-python): your change description"
# 2. Push the subdirectory to GitHub
git subtree push --prefix=projects/clink/mcp-python github-mcp-python main
```
Or use the make target:
```bash
make mcp-python-publish
```
### Important notes
- Always commit to the monorepo first, then push to GitHub
- The GitHub repo's `main` branch mirrors this directory
- Don't edit the GitHub repo directly - changes flow monorepo -> GitHub only
## Publishing to PyPI
After pushing to GitHub:
```bash
cd projects/clink/mcp-python
# Bump version in pyproject.toml, then:
uv build
uv publish
```
Or with hatch:
```bash
hatch version patch # or minor/major
hatch build
hatch publish
```
Then commit the version bump to the monorepo and push to GitHub again.
## Development
### Setup
```bash
cd projects/clink/mcp-python
uv venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"
```
### Testing locally with Claude Code
1. Update your `~/.claude.json` to use the local source:
```json
{
"mcpServers": {
"clink": {
"command": "python",
"args": ["-m", "clink_mcp_server"],
"env": {
"CLINK_API_KEY": "sk_live_...",
"CLINK_API_URL": "https://api.stg.clink.voxos.ai",
"PYTHONPATH": "/path/to/voxos/projects/clink/mcp-python/src"
}
}
}
}
```
2. Restart Claude Code
### Running Tests
```bash
pytest tests/
```
## Project Structure
```
src/clink_mcp_server/
__init__.py # Package init, exports main()
__main__.py # Entry point for python -m
server.py # FastMCP server setup
client.py # HTTP client for Clink API
types.py # Pydantic models
tools/
__init__.py # Tool registration
groups.py # list_groups, list_members
clinks.py # send_clink, get_clinks, check_inbox
claims.py # claim_clink, complete_clink, release_clink
milestones.py # 9 milestone/checkpoint tools
projects.py # 7 project tools
proposals.py # 5 consensus/voting tools
system.py # permissions, feedback, verifications
```
## Adding a New Tool
1. Add the tool to the appropriate file in `src/clink_mcp_server/tools/`:
```python
@mcp.tool()
async def your_tool(param: str) -> str:
"""What this tool does.
Args:
param: Parameter description
"""
try:
result = await client.your_api_method(param)
return f"Success: {result}"
except ClinkApiError as e:
return f"Error: {e}"
```
2. If needed, add the API method to `src/clink_mcp_server/client.py`
3. Test locally with Claude Code
## API Compatibility
The MCP server must stay compatible with the Clink API. When the API changes:
1. Update `src/clink_mcp_server/types.py` with new Pydantic models
2. Update `src/clink_mcp_server/client.py` with new/modified methods
3. Update affected tools in `src/clink_mcp_server/tools/`
4. Bump version appropriately (breaking changes = major)
## See Also
- [Node.js/npm version](../mcp/) - `@voxos-ai/clink-mcp-server`
