# Deployment Guide
This guide covers how to deploy and distribute the Codebase Insights MCP Server.
## PyPI Publishing
### Prerequisites
1. **PyPI Account**: Create an account at https://pypi.org/
2. **API Token**: Generate an API token at https://pypi.org/manage/account/token/
3. **Poetry**: Ensure Poetry is installed and configured
### One-Time Setup
```bash
# Configure PyPI token
poetry config pypi-token.pypi YOUR-PYPI-TOKEN
# Verify configuration
poetry config --list | grep pypi-token
```
### Publishing Workflow
#### 1. Update Version
Choose appropriate version bump based on changes:
- **Patch** (0.1.0 → 0.1.1): Bug fixes, small improvements
- **Minor** (0.1.0 → 0.2.0): New features, backward compatible
- **Major** (0.1.0 → 1.0.0): Breaking changes
```bash
# Update version
poetry version patch|minor|major
# Or set specific version
poetry version 1.2.3
```
#### 2. Update Changelog
Update `CHANGELOG.md` with new version details:
```markdown
## [0.1.1] - 2024-01-20
### Added
- New Spring Boot analyzer improvements
- Better request body detection
### Fixed
- Fixed regex patterns for @RequestBody @Valid order
- Improved error handling for authentication
### Changed
- Updated README with uvx instructions
```
#### 3. Build and Test
```bash
# Build the package
poetry build
# Test build locally (optional)
pip install dist/codebase_insights_mcp-*.whl
```
#### 4. Publish to PyPI
```bash
# Publish to PyPI
poetry publish
# Or build and publish in one step
poetry publish --build
```
#### 5. Verify Publication
```bash
# Test installation from PyPI
uvx codebase-insights-mcp --version
# Or
pip install codebase-insights-mcp
```
### Automated Publishing Script
Create a script `scripts/release.sh`:
```bash
#!/bin/bash
set -e
# Get version type (patch, minor, major)
VERSION_TYPE=${1:-patch}
echo "🚀 Starting release process..."
# Update version
echo "📝 Updating version ($VERSION_TYPE)..."
poetry version $VERSION_TYPE
# Get new version
NEW_VERSION=$(poetry version --short)
echo "📦 New version: $NEW_VERSION"
# Build package
echo "🔨 Building package..."
poetry build
# Publish to PyPI
echo "📤 Publishing to PyPI..."
poetry publish
# Verify installation
echo "✅ Verifying installation..."
uvx --reinstall codebase-insights-mcp
echo "🎉 Release $NEW_VERSION completed successfully!"
echo "Users can now update with: uvx --reinstall codebase-insights-mcp"
```
Make it executable:
```bash
chmod +x scripts/release.sh
```
Usage:
```bash
# Patch release
./scripts/release.sh patch
# Minor release
./scripts/release.sh minor
# Major release
./scripts/release.sh major
```
## User Installation Methods
### Method 1: uvx (Recommended)
This is the easiest method for end users:
```bash
# One-time installation
uvx codebase-insights-mcp
# Install globally
uv tool install codebase-insights-mcp
# Update to latest version
uvx --reinstall codebase-insights-mcp
```
### Method 2: pip
Traditional pip installation:
```bash
# Install globally
pip install codebase-insights-mcp
# Update
pip install --upgrade codebase-insights-mcp
```
### Method 3: pipx
Alternative to uvx:
```bash
# Install with pipx
pipx install codebase-insights-mcp
# Update
pipx upgrade codebase-insights-mcp
```
## Claude Desktop Configuration
### For uvx Users (Recommended)
```json
{
"mcpServers": {
"codebase-insights": {
"command": "uvx",
"args": ["--no-cache", "codebase-insights-mcp"],
"env": {
"BITBUCKET_EMAIL": "your-username",
"BITBUCKET_API_TOKEN": "your-app-password",
"output_directory": "/Users/username/postman-collections"
}
}
}
}
```
### For Global pip Installation
```json
{
"mcpServers": {
"codebase-insights": {
"command": "codebase-insights-mcp",
"env": {
"BITBUCKET_EMAIL": "your-username",
"BITBUCKET_API_TOKEN": "your-app-password",
"output_directory": "/Users/username/postman-collections"
}
}
}
}
```
### For Development
```json
{
"mcpServers": {
"codebase-insights": {
"command": "poetry",
"args": ["run", "codebase-insights-mcp"],
"cwd": "/path/to/codebase-insights-mcp",
"env": {
"BITBUCKET_EMAIL": "your-username",
"BITBUCKET_API_TOKEN": "your-app-password",
"output_directory": "/Users/username/postman-collections"
}
}
}
}
```
## Distribution Checklist
Before each release, verify:
- [ ] All tests pass
- [ ] Version number updated
- [ ] CHANGELOG.md updated
- [ ] README.md reflects latest features
- [ ] Dependencies are up to date
- [ ] Build succeeds without warnings
- [ ] Installation works via uvx
- [ ] MCP server starts successfully
- [ ] Claude Desktop configuration works
## Troubleshooting
### Build Issues
```bash
# Clear Poetry cache
poetry cache clear pypi --all
# Reinstall dependencies
poetry install --sync
```
### Publishing Issues
```bash
# Check PyPI token
poetry config --list | grep pypi-token
# Test with dry run
poetry publish --dry-run
```
### Installation Issues
```bash
# Clear uvx cache
uvx --clear-cache
# Force reinstall
uvx --reinstall codebase-insights-mcp
```
## Testing with HTTP Transport
### MCP Inspector Testing
For development and testing, you can run the server in HTTP mode and test with MCP Inspector:
#### Quick Test Setup
```bash
# Set up environment
export BITBUCKET_EMAIL="your-username"
export BITBUCKET_API_TOKEN="your-app-password"
export output_directory="/tmp/postman-test"
# Test published version
uvx codebase-insights-mcp@latest --transport http --port 8000
# Test development version
poetry run codebase-insights-mcp --transport http --port 8000
```
#### MCP Inspector Connection
1. **Open MCP Inspector**: https://inspector.mcphub.com/
2. **Server URL**: `http://localhost:8000/mcp`
3. **Click Connect**
#### Test Payloads
**Test generate_collection:**
```json
{
"repo_url": "https://bitbucket.org/tymerepos/tb-payshap-svc.git"
}
```
**Test get_server_info:**
```json
{}
```
#### Expected Responses
**generate_collection response:**
```json
{
"success": true,
"collection_path": "/tmp/postman-test/tb-payshap-svc_postman_collection.json",
"message": "Generated Postman collection with X endpoints",
"endpoints_count": 8,
"errors": []
}
```
**get_server_info response:**
```json
{
"name": "codebase-insights",
"version": "0.1.3",
"description": "MCP server for generating Postman collections from API codebases",
"capabilities": {
"supported_frameworks": ["FastAPI", "Spring Boot", "Flask (coming soon)"],
"supported_specs": ["OpenAPI 3.x", "Swagger 2.0"],
"output_format": "Postman Collection v2.1"
}
}
```
### Test Script Usage
The project includes multiple scripts for HTTP testing:
#### Interactive MCP Inspector Testing
```bash
# Basic usage (auto-detects installation method)
./test_mcp_inspector.sh
# Test specific published version
./test_mcp_inspector.sh --version 0.1.3
# Test latest published version
./test_mcp_inspector.sh --latest
```
The script will:
- Check environment variables
- Set default output directory
- Show connection instructions and test payloads
- Start the server in HTTP mode
- Provide fallback to different installation methods
#### Automated HTTP API Testing
```bash
# Test with default repository
./scripts/test_http_api.sh
# Test with custom repository
./scripts/test_http_api.sh "https://github.com/user/repo.git"
```
The HTTP API test script will:
- Check server availability
- Test `tools/list` endpoint
- Test `get_server_info` tool
- Test `generate_collection` tool
- Display formatted JSON responses (if `jq` is installed)
### HTTP vs STDIO Transport
| Transport | Use Case | Connection |
|-----------|----------|------------|
| **STDIO** | Production with Claude Desktop | Pipe communication |
| **HTTP** | Development & Testing | HTTP endpoint at `/mcp` |
### Integration Testing
For automated testing, you can use curl to test the HTTP endpoint:
```bash
# Start server in background
uvx codebase-insights-mcp --transport http --port 8000 &
SERVER_PID=$!
# Test server info
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_server_info",
"arguments": {}
}
}'
# Test collection generation
curl -X POST http://localhost:8000/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "generate_collection",
"arguments": {
"input": {
"repo_url": "https://github.com/public/repo.git"
}
}
}
}'
# Clean up
kill $SERVER_PID
```
## Monitoring
After each release:
1. **Download Stats**: Monitor downloads at https://pypistats.org/packages/codebase-insights-mcp
2. **Issues**: Watch GitHub issues for bug reports
3. **Claude Desktop**: Test with actual Claude Desktop configuration
4. **Feedback**: Monitor user feedback and feature requests
