# MCP Jive - AI-Powered Development Workflow Manager
**🤖 Built for Developers using AI Agents** | **🧠 Intelligent Memory System** | **⚡ 8 Consolidated Tools**
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://lancedb.com/)
[](https://opensource.org/licenses/MIT)
---
## 🎯 What is MCP Jive?
**MCP Jive transforms how AI agents manage your development workflow.** It's an intelligent project management system designed specifically for developers who code with AI assistants like Claude, Cursor, and other MCP-compatible tools.
### Why MCP Jive?
When you're building software with AI agents, you need more than a task list. You need:
- **📝 Context Persistence** - AI agents remember architectural decisions and solutions
- **🧠 Smart Memory** - Store patterns, gotchas, and solutions for instant recall
- **🔗 Intelligent Linking** - Connect work items to architecture docs and troubleshooting guides
- **⚡ Built for Speed** - Optimized for AI agent workflows, not manual clicking
---
## ✨ Key Features
### 🧠 **AI Memory System**
The game-changer for AI-powered development. MCP Jive includes two types of persistent memory:
**Architecture Memory**
- 📐 **Store patterns & decisions** - Document how you built features, why you chose specific approaches
- 🔗 **Link to work items** - Connect epics to architectural patterns automatically
- 🎯 **Context-aware retrieval** - AI agents get relevant architecture when implementing features
- 🌲 **Hierarchical organization** - Parent-child relationships for complex architectures
**Troubleshooting Memory**
- 🐛 **Capture solutions** - Save fixes to cryptic errors and gotchas
- 🔍 **Smart matching** - AI agents find solutions based on problem descriptions
- ⚡ **Instant recall** - Never solve the same problem twice
- 📊 **Usage tracking** - See which solutions are most valuable
**How AI Agents Use Memory:**
```
You: "Implement JWT authentication for the API"
AI Agent:
1. Searches Architecture Memory for "jwt" and "authentication"
2. Finds your documented pattern: "jwt-auth-api-pattern"
3. Retrieves implementation details, gotchas, and best practices
4. Implements using your established pattern - consistent every time
```
### 🏗️ **Intelligent Work Structure**
Hierarchical project management designed for how AI agents think:
```
📋 Initiative (1-3 months)
├── 📊 Epic (2-4 weeks) ← Links to Architecture Memory
│ ├── 🎯 Feature (3-5 days)
│ │ ├── 📝 Story (1-2 days)
│ │ └── ✅ Task (1-4 hours)
```
- **Auto-dependencies** - AI agents understand what to build first
- **Progress tracking** - Real-time completion analytics
- **Namespace isolation** - Separate projects never mix
### 🔍 **Vector-Powered Search**
Built on LanceDB for lightning-fast semantic search:
- **Hybrid search** - Combines semantic similarity + keywords
- **Finds relevant context** - Even when you don't use exact words
- **Namespace-aware** - Search within project boundaries
---
## 🚀 Quick Start
### Installation (< 30 seconds) ⚡
**No git, no setup, no configuration files needed!**
#### Option 1: Using `uvx` (Recommended - Single Command)
```bash
# Run MCP Jive directly - no installation needed!
uvx mcp-jive server --port 3454 --http
# Server starts immediately at http://localhost:3454
```
**That's it!** MCP Jive downloads, installs dependencies, and starts in one command.
---
#### Option 2: Using `pip` (Traditional Install)
```bash
# Install once
pip install mcp-jive
# Run anytime
mcp-jive server --port 3454 --http
# Verify it's running
curl http://localhost:3454/health
# Response: {"status": "healthy", "version": "1.4.0"}
```
---
#### Option 3: From Source (For Development)
```bash
# Clone and setup
git clone <repository-url>
cd mcp-jive
./bin/mcp-jive setup environment
# Start the server
./bin/mcp-jive server start
```
**Choose `uvx` for the fastest experience!** No Python environment management needed.
---
## 🔌 Connect Your IDE (< 5 minutes)
MCP Jive works with all major AI coding tools. Choose your setup below:
### 🔷 VSCode with Copilot / MCP Extension
**Create `.vscode/mcp.json` in your project:**
```json
{
"servers": {
"mcp-jive": {
"type": "http",
"url": "http://localhost:3454/mcp/my-project"
}
}
}
```
**Or add globally:** Run `MCP: Add Server` from Command Palette and select "Global".
**Note:** Replace `my-project` with your project name for namespace isolation.
---
### 🔶 Cursor IDE
**Create `.cursor/mcp.json` in your project root:**
```json
{
"mcpServers": {
"mcp-jive": {
"type": "http",
"url": "http://localhost:3454/mcp/my-project"
}
}
}
```
**Or configure globally:** Create/edit `~/.cursor/mcp.json` with the same structure.
**Note:** Replace `my-project` with your project name for namespace isolation.
---
### 🔵 Claude Code (Anthropic)
**Option 1: Using CLI (Recommended)**
```bash
# Add MCP server for current project
claude mcp add mcp-jive \
--scope project \
--type http \
--url http://localhost:3454/mcp/my-project
# Or add globally for all projects
claude mcp add mcp-jive \
--scope global \
--type http \
--url http://localhost:3454/mcp/my-project
```
**Option 2: Manual Configuration**
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"mcp-jive": {
"type": "http",
"url": "http://localhost:3454/mcp/my-project"
}
}
}
```
**Start coding:**
```bash
claude-code
# MCP Jive will be automatically connected
```
**Useful commands:**
```bash
# List configured MCP servers
claude mcp list
# Remove a server
claude mcp remove mcp-jive
# Reset project-scoped server approvals
claude mcp reset-project-choices
```
---
### 🔺 Trae / Kiro / Other MCP IDEs
Most MCP-compatible IDEs follow the standard MCP configuration format.
**Check your IDE's documentation for:**
1. Configuration file location (usually `.mcp.json`, `mcp.json`, or IDE-specific)
2. Whether it uses `"servers"` or `"mcpServers"` key
3. Supported transport types (stdio, http, sse)
**Common formats:**
```json
// Format 1 (VSCode-style)
{
"servers": {
"mcp-jive": {
"type": "http",
"url": "http://localhost:3454/mcp/<your-project-name>"
}
}
}
// Format 2 (Cursor/Claude Code-style)
{
"mcpServers": {
"mcp-jive": {
"type": "http",
"url": "http://localhost:3454/mcp/<your-project-name>"
}
}
}
```
---
### ✅ Verify Connection
Ask your AI agent:
```
"List all available tools"
```
You should see 8 `jive_*` tools including:
- ✅ `jive_manage_work_item`
- ✅ `jive_memory` (Architecture & Troubleshooting)
- ✅ `jive_search_content`
- ✅ `jive_get_hierarchy`
- ✅ `jive_track_progress`
---
## 💡 How to Use MCP Jive
### For Developers Using AI Agents
MCP Jive is designed to be used through **natural conversation with your AI agent**. Here's how:
#### 1️⃣ **Plan Your Work**
```
You: "I need to add user authentication to my app"
AI Agent: Creates structured work breakdown:
📊 Epic: User Authentication System
├── 🎯 Feature: Login/Logout
│ ├── ✅ Task: JWT token generation
│ ├── ✅ Task: Token validation middleware
│ └── ✅ Task: Write authentication tests
├── 🎯 Feature: Password Management
└── 🎯 Feature: Session Handling
```
#### 2️⃣ **Document Patterns**
```
You: "Save our JWT implementation as an architecture pattern"
AI Agent: Creates Architecture Memory:
- Title: "JWT Authentication API Pattern"
- When to use: REST API authentication, stateless auth required
- Implementation: [Your documented approach]
- Gotchas: Token expiry, refresh strategy, secret rotation
- Links to Epic: User Authentication System
```
#### 3️⃣ **Reuse Knowledge**
```
You: "Implement OAuth for the mobile app"
AI Agent:
1. Searches Architecture Memory for "authentication" patterns
2. Finds "JWT Authentication API Pattern"
3. Adapts the pattern for OAuth
4. Implements consistently with existing auth approach
```
#### 4️⃣ **Capture Solutions**
```
You: "This CORS preflight error is annoying"
AI Agent: "Let me save this for next time"
Creates Troubleshooting Memory:
- Problem: CORS preflight requests failing
- Solution: Configure Express CORS middleware
- Code snippet: [Exact fix]
- Next time: Instant solution, no debugging
```
---
### Common Commands
**Project Management:**
- `"Create an epic for implementing payments"`
- `"Break down the authentication epic into tasks"`
- `"Show me what's blocking the API development"`
- `"What should I work on next?"`
**Using Memory:**
- `"Document our React component pattern as architecture"`
- `"Search architecture memory for database patterns"`
- `"Save the fix for this webpack error to troubleshooting memory"`
- `"Find solutions for Next.js hydration errors"`
**Progress Tracking:**
- `"Show progress on the mobile app initiative"`
- `"Mark the JWT task as completed"`
- `"What's the completion percentage for this sprint?"`
- `"Generate a status report"`
**Namespace Management:**
- `"Switch to the mobile-app namespace"`
- `"List all work items in this project"`
- `"Show me architecture patterns for the backend namespace"`
---
## 🧠 Memory System Deep Dive
### Architecture Memory
**What it stores:**
- Design patterns and approaches
- Technology choices and trade-offs
- Integration guides
- Code conventions and standards
- API designs and data models
**Example Use Cases:**
```
Pattern: "React Form Validation"
└─ When to use: Complex forms, user input validation
└─ Requirements: Use Formik + Yup, custom error handling
└─ Children: "Email Validation", "Password Strength Check"
└─ Linked Epics: User Registration, Profile Editing
```
**AI Agent Benefits:**
- Consistent implementation across features
- No need to re-decide architecture choices
- Instant context when starting new work
- Architectural knowledge persists across sessions
### Troubleshooting Memory
**What it stores:**
- Common errors and solutions
- Configuration gotchas
- Debugging strategies
- Workarounds for library quirks
- Environment setup issues
**Example Use Cases:**
```
Problem: "Module not found after npm install"
└─ Use cases: Build failures, missing dependencies
└─ Solution:
1. Delete node_modules and package-lock.json
2. Clear npm cache: npm cache clean --force
3. Reinstall: npm install
└─ Success rate: 94% (used 17 times)
```
**AI Agent Benefits:**
- Skip repetitive debugging
- Apply proven solutions immediately
- Learn from past mistakes
- Build institutional knowledge
---
## 🎯 Real-World Example Workflow
```
Day 1: Starting a New Feature
──────────────────────────────
You: "I need to add payment processing to the e-commerce app"
AI Agent:
✅ Creates Epic: "Payment Processing Integration"
✅ Searches Architecture Memory for "payment", "stripe", "api"
✅ Finds pattern: "Third-Party API Integration"
✅ Creates features: Stripe Setup, Checkout Flow, Webhooks
✅ Links Epic to architecture pattern
You: "Start implementing Stripe integration"
AI Agent:
✅ Retrieves architecture pattern + implementation guide
✅ Implements following your established conventions
✅ Marks tasks complete as implementation progresses
Day 2: Hit an Error
────────────────────
You: "Stripe webhook signature validation keeps failing"
AI Agent:
✅ Checks Troubleshooting Memory for "stripe webhook"
❌ No existing solution found
✅ Debugs and solves the issue
✅ Saves solution to Troubleshooting Memory
You: "Great, save that fix"
Day 5: New Developer Joins
──────────────────────────────
New Dev: "I need to add PayPal integration"
AI Agent:
✅ Searches Architecture Memory: "payment", "api integration"
✅ Retrieves: "Third-Party API Integration" + "Stripe Integration"
✅ Searches Troubleshooting Memory: "webhook"
✅ Finds: "Stripe webhook signature validation"
✅ Implements PayPal using proven patterns + avoids known issues
✅ Consistent with existing codebase - no architectural drift
```
---
## 🏢 Namespace Isolation
**Each project gets its own isolated data:**
```
Namespaces:
├── mobile-app
│ ├── Work Items: Mobile-specific features
│ ├── Architecture: React Native patterns
│ └── Troubleshooting: Mobile debugging solutions
│
├── backend-api
│ ├── Work Items: API development tasks
│ ├── Architecture: REST API patterns, DB schemas
│ └── Troubleshooting: Server-side errors
│
└── web-dashboard
├── Work Items: Dashboard features
├── Architecture: Next.js patterns
└── Troubleshooting: Frontend build issues
```
**Benefits:**
- ✅ Complete data separation
- ✅ Per-project AI context
- ✅ Team-specific patterns
- ✅ No cross-contamination
---
## 📚 Available Tools
MCP Jive provides 8 consolidated tools that AI agents use automatically:
1. **`jive_manage_work_item`** - Create, update, delete work items
2. **`jive_get_work_item`** - Retrieve and list with filtering
3. **`jive_search_content`** - Semantic + keyword search
4. **`jive_get_hierarchy`** - Navigate dependencies and relationships
5. **`jive_execute_work_item`** - Workflow automation
6. **`jive_track_progress`** - Analytics and reporting
7. **`jive_sync_data`** - Backup and synchronization
8. **`jive_memory`** - Architecture & Troubleshooting memory
**You don't call these directly** - your AI agent uses them automatically based on your natural language requests.
---
## 🌐 Web Interface
Access the web UI at `http://localhost:3454/`
**Features:**
- 📊 **Analytics Dashboard** - Visual progress tracking
- 📋 **Work Items** - Manage tasks and epics
- 🧠 **Architecture Memory** - Browse and edit patterns
- 🔧 **Troubleshoot Memory** - Review saved solutions
- 🔄 **Namespace Switcher** - Toggle between projects
- ⚙️ **Settings** - Configure preferences
The web UI shares the same data as your IDE - changes sync in real-time.
---
## ⚙️ Configuration
### Environment Variables
Create `.env` in your MCP Jive directory:
```bash
# Server
MCP_JIVE_PORT=3454
MCP_JIVE_HOST=localhost
MCP_JIVE_DEBUG=false
# Database (LanceDB - embedded, no external DB needed)
LANCEDB_DATA_PATH=./data/lancedb
LANCEDB_EMBEDDING_MODEL=all-MiniLM-L6-v2
# Namespace (optional - can use URL-based namespaces instead)
MCP_JIVE_DEFAULT_NAMESPACE=default
```
### Server Modes
```bash
# Combined mode (default) - Web UI + MCP
./bin/mcp-jive server start
# Development mode (port 3456, with auto-reload)
./bin/mcp-jive dev server
# Production mode with custom port
./bin/mcp-jive server start --port 8080
```
---
## 🐛 Troubleshooting
### Common Issues
**"Server not starting"**
```bash
# Check Python version (need 3.9+)
python --version
# Verify installation
./bin/mcp-jive setup environment
# Check logs
./bin/mcp-jive server start --debug
```
**"IDE can't connect"**
```bash
# Verify server is running
curl http://localhost:3454/health
# Test MCP endpoint
curl -X POST http://localhost:3454/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
**"No tools appearing in IDE"**
1. Restart your IDE
2. Check MCP configuration file exists:
- VSCode: `.vscode/mcp.json`
- Cursor: `.cursor/mcp.json` or `~/.cursor/mcp.json`
- Claude Code: `.mcp.json` in project root
3. Verify correct JSON format for your IDE (see IDE setup sections)
4. Ensure server URL is correct: `http://localhost:3454/mcp/<namespace>`
**"Wrong namespace data"**
- Check your IDE config - each project should have unique namespace
- Verify URL: `http://localhost:3454/mcp/<your-project-name>`
- Use web UI namespace dropdown to confirm correct namespace
### Getting Help
- 📖 **Full Documentation**: [docs/README.md](docs/README.md)
- 🏗️ **Architecture Guide**: [docs/architecture/](docs/architecture/)
- 📋 **AI Agent Instructions**: [docs/guides/agent-jive-instructions.md](docs/guides/agent-jive-instructions.md)
- 🐛 **Issues**: [GitHub Issues](https://github.com/your-repo/issues)
---
## 🤝 Contributing
We welcome contributions! MCP Jive is built by developers for developers.
### Quick Development Setup
```bash
# Clone and setup
git clone <repository-url>
cd mcp-jive
./bin/mcp-jive setup environment
# Start development server (port 3456 with auto-reload)
./bin/mcp-jive dev server
# Run tests
python -m pytest
# Run linting
python -m pylint src/
```
### Contribution Areas
- 🧠 **Memory System** - Enhance AI context retrieval
- 🔍 **Search** - Improve semantic search algorithms
- 🎨 **Web UI** - Frontend improvements
- 📝 **Documentation** - Guides and examples
- 🔌 **Integrations** - New IDE support
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
---
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
Free to use, modify, and distribute in your projects.
---
## 🙏 Built With
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - IDE integration foundation
- **[LanceDB](https://lancedb.com/)** - Embedded vector database for semantic search
- **[FastAPI](https://fastapi.tiangolo.com/)** - High-performance Python web framework
- **[Next.js](https://nextjs.org/)** - React framework for the web UI
- **[Anthropic Claude](https://www.anthropic.com/)** - AI-powered intelligence
---
## 🚀 Ready to Get Started?
```bash
# Fastest way - one command:
uvx mcp-jive server --port 3454 --http
# Or install with pip:
pip install mcp-jive && mcp-jive server --port 3454 --http
# Then configure your IDE (see Quick Start above)
```
**Join developers using AI agents to build better software, faster.**
---
## 📦 Distribution & Installation
For more installation options including Docker, see [DISTRIBUTION.md](DISTRIBUTION.md)
**Available on:**
- 📦 PyPI: `pip install mcp-jive` or `uvx mcp-jive`
- 🐳 Docker: `docker run mcpjive/mcp-jive:latest` (coming soon)
- 📥 Source: `git clone <repository-url>`
---
📚 [Documentation](docs/README.md) • 🔧 [Contributing](CONTRIBUTING.md) • 📦 [Distribution Guide](DISTRIBUTION.md) • 💬 [Discussions](https://github.com/your-repo/discussions) • 🐛 [Issues](https://github.com/your-repo/issues)
Raw data
{
"_id": null,
"home_page": "https://github.com/mcpjive/mcp-jive",
"name": "mcp-jive",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, ai, task-management, workflow, automation",
"author": "MCP Jive Team",
"author_email": "MCP Jive Team <team@mcpjive.com>",
"download_url": "https://files.pythonhosted.org/packages/ff/97/be8c4753d1f56ed44de1114cebea41180af317ad33ae9cd03df82d4d2c31/mcp_jive-1.4.0.tar.gz",
"platform": null,
"description": "# MCP Jive - AI-Powered Development Workflow Manager\n\n**\ud83e\udd16 Built for Developers using AI Agents** | **\ud83e\udde0 Intelligent Memory System** | **\u26a1 8 Consolidated Tools**\n\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io/)\n[](https://lancedb.com/)\n[](https://opensource.org/licenses/MIT)\n\n---\n\n## \ud83c\udfaf What is MCP Jive?\n\n**MCP Jive transforms how AI agents manage your development workflow.** It's an intelligent project management system designed specifically for developers who code with AI assistants like Claude, Cursor, and other MCP-compatible tools.\n\n### Why MCP Jive?\n\nWhen you're building software with AI agents, you need more than a task list. You need:\n- **\ud83d\udcdd Context Persistence** - AI agents remember architectural decisions and solutions\n- **\ud83e\udde0 Smart Memory** - Store patterns, gotchas, and solutions for instant recall\n- **\ud83d\udd17 Intelligent Linking** - Connect work items to architecture docs and troubleshooting guides\n- **\u26a1 Built for Speed** - Optimized for AI agent workflows, not manual clicking\n\n---\n\n## \u2728 Key Features\n\n### \ud83e\udde0 **AI Memory System**\n\nThe game-changer for AI-powered development. MCP Jive includes two types of persistent memory:\n\n**Architecture Memory**\n- \ud83d\udcd0 **Store patterns & decisions** - Document how you built features, why you chose specific approaches\n- \ud83d\udd17 **Link to work items** - Connect epics to architectural patterns automatically\n- \ud83c\udfaf **Context-aware retrieval** - AI agents get relevant architecture when implementing features\n- \ud83c\udf32 **Hierarchical organization** - Parent-child relationships for complex architectures\n\n**Troubleshooting Memory**\n- \ud83d\udc1b **Capture solutions** - Save fixes to cryptic errors and gotchas\n- \ud83d\udd0d **Smart matching** - AI agents find solutions based on problem descriptions\n- \u26a1 **Instant recall** - Never solve the same problem twice\n- \ud83d\udcca **Usage tracking** - See which solutions are most valuable\n\n**How AI Agents Use Memory:**\n```\nYou: \"Implement JWT authentication for the API\"\n\nAI Agent:\n1. Searches Architecture Memory for \"jwt\" and \"authentication\"\n2. Finds your documented pattern: \"jwt-auth-api-pattern\"\n3. Retrieves implementation details, gotchas, and best practices\n4. Implements using your established pattern - consistent every time\n```\n\n### \ud83c\udfd7\ufe0f **Intelligent Work Structure**\n\nHierarchical project management designed for how AI agents think:\n\n```\n\ud83d\udccb Initiative (1-3 months)\n \u251c\u2500\u2500 \ud83d\udcca Epic (2-4 weeks) \u2190 Links to Architecture Memory\n \u2502 \u251c\u2500\u2500 \ud83c\udfaf Feature (3-5 days)\n \u2502 \u2502 \u251c\u2500\u2500 \ud83d\udcdd Story (1-2 days)\n \u2502 \u2502 \u2514\u2500\u2500 \u2705 Task (1-4 hours)\n```\n\n- **Auto-dependencies** - AI agents understand what to build first\n- **Progress tracking** - Real-time completion analytics\n- **Namespace isolation** - Separate projects never mix\n\n### \ud83d\udd0d **Vector-Powered Search**\n\nBuilt on LanceDB for lightning-fast semantic search:\n- **Hybrid search** - Combines semantic similarity + keywords\n- **Finds relevant context** - Even when you don't use exact words\n- **Namespace-aware** - Search within project boundaries\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Installation (< 30 seconds) \u26a1\n\n**No git, no setup, no configuration files needed!**\n\n#### Option 1: Using `uvx` (Recommended - Single Command)\n\n```bash\n# Run MCP Jive directly - no installation needed!\nuvx mcp-jive server --port 3454 --http\n\n# Server starts immediately at http://localhost:3454\n```\n\n**That's it!** MCP Jive downloads, installs dependencies, and starts in one command.\n\n---\n\n#### Option 2: Using `pip` (Traditional Install)\n\n```bash\n# Install once\npip install mcp-jive\n\n# Run anytime\nmcp-jive server --port 3454 --http\n\n# Verify it's running\ncurl http://localhost:3454/health\n# Response: {\"status\": \"healthy\", \"version\": \"1.4.0\"}\n```\n\n---\n\n#### Option 3: From Source (For Development)\n\n```bash\n# Clone and setup\ngit clone <repository-url>\ncd mcp-jive\n./bin/mcp-jive setup environment\n\n# Start the server\n./bin/mcp-jive server start\n```\n\n**Choose `uvx` for the fastest experience!** No Python environment management needed.\n\n---\n\n## \ud83d\udd0c Connect Your IDE (< 5 minutes)\n\nMCP Jive works with all major AI coding tools. Choose your setup below:\n\n### \ud83d\udd37 VSCode with Copilot / MCP Extension\n\n**Create `.vscode/mcp.json` in your project:**\n```json\n{\n \"servers\": {\n \"mcp-jive\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:3454/mcp/my-project\"\n }\n }\n}\n```\n\n**Or add globally:** Run `MCP: Add Server` from Command Palette and select \"Global\".\n\n**Note:** Replace `my-project` with your project name for namespace isolation.\n\n---\n\n### \ud83d\udd36 Cursor IDE\n\n**Create `.cursor/mcp.json` in your project root:**\n```json\n{\n \"mcpServers\": {\n \"mcp-jive\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:3454/mcp/my-project\"\n }\n }\n}\n```\n\n**Or configure globally:** Create/edit `~/.cursor/mcp.json` with the same structure.\n\n**Note:** Replace `my-project` with your project name for namespace isolation.\n\n---\n\n### \ud83d\udd35 Claude Code (Anthropic)\n\n**Option 1: Using CLI (Recommended)**\n```bash\n# Add MCP server for current project\nclaude mcp add mcp-jive \\\n --scope project \\\n --type http \\\n --url http://localhost:3454/mcp/my-project\n\n# Or add globally for all projects\nclaude mcp add mcp-jive \\\n --scope global \\\n --type http \\\n --url http://localhost:3454/mcp/my-project\n```\n\n**Option 2: Manual Configuration**\n\nCreate `.mcp.json` in your project root:\n```json\n{\n \"mcpServers\": {\n \"mcp-jive\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:3454/mcp/my-project\"\n }\n }\n}\n```\n\n**Start coding:**\n```bash\nclaude-code\n# MCP Jive will be automatically connected\n```\n\n**Useful commands:**\n```bash\n# List configured MCP servers\nclaude mcp list\n\n# Remove a server\nclaude mcp remove mcp-jive\n\n# Reset project-scoped server approvals\nclaude mcp reset-project-choices\n```\n\n---\n\n### \ud83d\udd3a Trae / Kiro / Other MCP IDEs\n\nMost MCP-compatible IDEs follow the standard MCP configuration format.\n\n**Check your IDE's documentation for:**\n1. Configuration file location (usually `.mcp.json`, `mcp.json`, or IDE-specific)\n2. Whether it uses `\"servers\"` or `\"mcpServers\"` key\n3. Supported transport types (stdio, http, sse)\n\n**Common formats:**\n```json\n// Format 1 (VSCode-style)\n{\n \"servers\": {\n \"mcp-jive\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:3454/mcp/<your-project-name>\"\n }\n }\n}\n\n// Format 2 (Cursor/Claude Code-style)\n{\n \"mcpServers\": {\n \"mcp-jive\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:3454/mcp/<your-project-name>\"\n }\n }\n}\n```\n\n---\n\n### \u2705 Verify Connection\n\nAsk your AI agent:\n```\n\"List all available tools\"\n```\n\nYou should see 8 `jive_*` tools including:\n- \u2705 `jive_manage_work_item`\n- \u2705 `jive_memory` (Architecture & Troubleshooting)\n- \u2705 `jive_search_content`\n- \u2705 `jive_get_hierarchy`\n- \u2705 `jive_track_progress`\n\n---\n\n## \ud83d\udca1 How to Use MCP Jive\n\n### For Developers Using AI Agents\n\nMCP Jive is designed to be used through **natural conversation with your AI agent**. Here's how:\n\n#### 1\ufe0f\u20e3 **Plan Your Work**\n\n```\nYou: \"I need to add user authentication to my app\"\n\nAI Agent: Creates structured work breakdown:\n \ud83d\udcca Epic: User Authentication System\n \u251c\u2500\u2500 \ud83c\udfaf Feature: Login/Logout\n \u2502 \u251c\u2500\u2500 \u2705 Task: JWT token generation\n \u2502 \u251c\u2500\u2500 \u2705 Task: Token validation middleware\n \u2502 \u2514\u2500\u2500 \u2705 Task: Write authentication tests\n \u251c\u2500\u2500 \ud83c\udfaf Feature: Password Management\n \u2514\u2500\u2500 \ud83c\udfaf Feature: Session Handling\n```\n\n#### 2\ufe0f\u20e3 **Document Patterns**\n\n```\nYou: \"Save our JWT implementation as an architecture pattern\"\n\nAI Agent: Creates Architecture Memory:\n - Title: \"JWT Authentication API Pattern\"\n - When to use: REST API authentication, stateless auth required\n - Implementation: [Your documented approach]\n - Gotchas: Token expiry, refresh strategy, secret rotation\n - Links to Epic: User Authentication System\n```\n\n#### 3\ufe0f\u20e3 **Reuse Knowledge**\n\n```\nYou: \"Implement OAuth for the mobile app\"\n\nAI Agent:\n 1. Searches Architecture Memory for \"authentication\" patterns\n 2. Finds \"JWT Authentication API Pattern\"\n 3. Adapts the pattern for OAuth\n 4. Implements consistently with existing auth approach\n```\n\n#### 4\ufe0f\u20e3 **Capture Solutions**\n\n```\nYou: \"This CORS preflight error is annoying\"\n\nAI Agent: \"Let me save this for next time\"\n Creates Troubleshooting Memory:\n - Problem: CORS preflight requests failing\n - Solution: Configure Express CORS middleware\n - Code snippet: [Exact fix]\n - Next time: Instant solution, no debugging\n```\n\n---\n\n### Common Commands\n\n**Project Management:**\n- `\"Create an epic for implementing payments\"`\n- `\"Break down the authentication epic into tasks\"`\n- `\"Show me what's blocking the API development\"`\n- `\"What should I work on next?\"`\n\n**Using Memory:**\n- `\"Document our React component pattern as architecture\"`\n- `\"Search architecture memory for database patterns\"`\n- `\"Save the fix for this webpack error to troubleshooting memory\"`\n- `\"Find solutions for Next.js hydration errors\"`\n\n**Progress Tracking:**\n- `\"Show progress on the mobile app initiative\"`\n- `\"Mark the JWT task as completed\"`\n- `\"What's the completion percentage for this sprint?\"`\n- `\"Generate a status report\"`\n\n**Namespace Management:**\n- `\"Switch to the mobile-app namespace\"`\n- `\"List all work items in this project\"`\n- `\"Show me architecture patterns for the backend namespace\"`\n\n---\n\n## \ud83e\udde0 Memory System Deep Dive\n\n### Architecture Memory\n\n**What it stores:**\n- Design patterns and approaches\n- Technology choices and trade-offs\n- Integration guides\n- Code conventions and standards\n- API designs and data models\n\n**Example Use Cases:**\n\n```\nPattern: \"React Form Validation\"\n\u2514\u2500 When to use: Complex forms, user input validation\n\u2514\u2500 Requirements: Use Formik + Yup, custom error handling\n\u2514\u2500 Children: \"Email Validation\", \"Password Strength Check\"\n\u2514\u2500 Linked Epics: User Registration, Profile Editing\n```\n\n**AI Agent Benefits:**\n- Consistent implementation across features\n- No need to re-decide architecture choices\n- Instant context when starting new work\n- Architectural knowledge persists across sessions\n\n### Troubleshooting Memory\n\n**What it stores:**\n- Common errors and solutions\n- Configuration gotchas\n- Debugging strategies\n- Workarounds for library quirks\n- Environment setup issues\n\n**Example Use Cases:**\n\n```\nProblem: \"Module not found after npm install\"\n\u2514\u2500 Use cases: Build failures, missing dependencies\n\u2514\u2500 Solution:\n 1. Delete node_modules and package-lock.json\n 2. Clear npm cache: npm cache clean --force\n 3. Reinstall: npm install\n\u2514\u2500 Success rate: 94% (used 17 times)\n```\n\n**AI Agent Benefits:**\n- Skip repetitive debugging\n- Apply proven solutions immediately\n- Learn from past mistakes\n- Build institutional knowledge\n\n---\n\n## \ud83c\udfaf Real-World Example Workflow\n\n```\nDay 1: Starting a New Feature\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nYou: \"I need to add payment processing to the e-commerce app\"\n\nAI Agent:\n \u2705 Creates Epic: \"Payment Processing Integration\"\n \u2705 Searches Architecture Memory for \"payment\", \"stripe\", \"api\"\n \u2705 Finds pattern: \"Third-Party API Integration\"\n \u2705 Creates features: Stripe Setup, Checkout Flow, Webhooks\n \u2705 Links Epic to architecture pattern\n\nYou: \"Start implementing Stripe integration\"\n\nAI Agent:\n \u2705 Retrieves architecture pattern + implementation guide\n \u2705 Implements following your established conventions\n \u2705 Marks tasks complete as implementation progresses\n\n\nDay 2: Hit an Error\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nYou: \"Stripe webhook signature validation keeps failing\"\n\nAI Agent:\n \u2705 Checks Troubleshooting Memory for \"stripe webhook\"\n \u274c No existing solution found\n \u2705 Debugs and solves the issue\n \u2705 Saves solution to Troubleshooting Memory\n\nYou: \"Great, save that fix\"\n\n\nDay 5: New Developer Joins\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nNew Dev: \"I need to add PayPal integration\"\n\nAI Agent:\n \u2705 Searches Architecture Memory: \"payment\", \"api integration\"\n \u2705 Retrieves: \"Third-Party API Integration\" + \"Stripe Integration\"\n \u2705 Searches Troubleshooting Memory: \"webhook\"\n \u2705 Finds: \"Stripe webhook signature validation\"\n \u2705 Implements PayPal using proven patterns + avoids known issues\n \u2705 Consistent with existing codebase - no architectural drift\n```\n\n---\n\n## \ud83c\udfe2 Namespace Isolation\n\n**Each project gets its own isolated data:**\n\n```\nNamespaces:\n\u251c\u2500\u2500 mobile-app\n\u2502 \u251c\u2500\u2500 Work Items: Mobile-specific features\n\u2502 \u251c\u2500\u2500 Architecture: React Native patterns\n\u2502 \u2514\u2500\u2500 Troubleshooting: Mobile debugging solutions\n\u2502\n\u251c\u2500\u2500 backend-api\n\u2502 \u251c\u2500\u2500 Work Items: API development tasks\n\u2502 \u251c\u2500\u2500 Architecture: REST API patterns, DB schemas\n\u2502 \u2514\u2500\u2500 Troubleshooting: Server-side errors\n\u2502\n\u2514\u2500\u2500 web-dashboard\n \u251c\u2500\u2500 Work Items: Dashboard features\n \u251c\u2500\u2500 Architecture: Next.js patterns\n \u2514\u2500\u2500 Troubleshooting: Frontend build issues\n```\n\n**Benefits:**\n- \u2705 Complete data separation\n- \u2705 Per-project AI context\n- \u2705 Team-specific patterns\n- \u2705 No cross-contamination\n\n---\n\n## \ud83d\udcda Available Tools\n\nMCP Jive provides 8 consolidated tools that AI agents use automatically:\n\n1. **`jive_manage_work_item`** - Create, update, delete work items\n2. **`jive_get_work_item`** - Retrieve and list with filtering\n3. **`jive_search_content`** - Semantic + keyword search\n4. **`jive_get_hierarchy`** - Navigate dependencies and relationships\n5. **`jive_execute_work_item`** - Workflow automation\n6. **`jive_track_progress`** - Analytics and reporting\n7. **`jive_sync_data`** - Backup and synchronization\n8. **`jive_memory`** - Architecture & Troubleshooting memory\n\n**You don't call these directly** - your AI agent uses them automatically based on your natural language requests.\n\n---\n\n## \ud83c\udf10 Web Interface\n\nAccess the web UI at `http://localhost:3454/`\n\n**Features:**\n- \ud83d\udcca **Analytics Dashboard** - Visual progress tracking\n- \ud83d\udccb **Work Items** - Manage tasks and epics\n- \ud83e\udde0 **Architecture Memory** - Browse and edit patterns\n- \ud83d\udd27 **Troubleshoot Memory** - Review saved solutions\n- \ud83d\udd04 **Namespace Switcher** - Toggle between projects\n- \u2699\ufe0f **Settings** - Configure preferences\n\nThe web UI shares the same data as your IDE - changes sync in real-time.\n\n---\n\n## \u2699\ufe0f Configuration\n\n### Environment Variables\n\nCreate `.env` in your MCP Jive directory:\n\n```bash\n# Server\nMCP_JIVE_PORT=3454\nMCP_JIVE_HOST=localhost\nMCP_JIVE_DEBUG=false\n\n# Database (LanceDB - embedded, no external DB needed)\nLANCEDB_DATA_PATH=./data/lancedb\nLANCEDB_EMBEDDING_MODEL=all-MiniLM-L6-v2\n\n# Namespace (optional - can use URL-based namespaces instead)\nMCP_JIVE_DEFAULT_NAMESPACE=default\n```\n\n### Server Modes\n\n```bash\n# Combined mode (default) - Web UI + MCP\n./bin/mcp-jive server start\n\n# Development mode (port 3456, with auto-reload)\n./bin/mcp-jive dev server\n\n# Production mode with custom port\n./bin/mcp-jive server start --port 8080\n```\n\n---\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n**\"Server not starting\"**\n```bash\n# Check Python version (need 3.9+)\npython --version\n\n# Verify installation\n./bin/mcp-jive setup environment\n\n# Check logs\n./bin/mcp-jive server start --debug\n```\n\n**\"IDE can't connect\"**\n```bash\n# Verify server is running\ncurl http://localhost:3454/health\n\n# Test MCP endpoint\ncurl -X POST http://localhost:3454/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\n**\"No tools appearing in IDE\"**\n1. Restart your IDE\n2. Check MCP configuration file exists:\n - VSCode: `.vscode/mcp.json`\n - Cursor: `.cursor/mcp.json` or `~/.cursor/mcp.json`\n - Claude Code: `.mcp.json` in project root\n3. Verify correct JSON format for your IDE (see IDE setup sections)\n4. Ensure server URL is correct: `http://localhost:3454/mcp/<namespace>`\n\n**\"Wrong namespace data\"**\n- Check your IDE config - each project should have unique namespace\n- Verify URL: `http://localhost:3454/mcp/<your-project-name>`\n- Use web UI namespace dropdown to confirm correct namespace\n\n### Getting Help\n\n- \ud83d\udcd6 **Full Documentation**: [docs/README.md](docs/README.md)\n- \ud83c\udfd7\ufe0f **Architecture Guide**: [docs/architecture/](docs/architecture/)\n- \ud83d\udccb **AI Agent Instructions**: [docs/guides/agent-jive-instructions.md](docs/guides/agent-jive-instructions.md)\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/your-repo/issues)\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! MCP Jive is built by developers for developers.\n\n### Quick Development Setup\n\n```bash\n# Clone and setup\ngit clone <repository-url>\ncd mcp-jive\n./bin/mcp-jive setup environment\n\n# Start development server (port 3456 with auto-reload)\n./bin/mcp-jive dev server\n\n# Run tests\npython -m pytest\n\n# Run linting\npython -m pylint src/\n```\n\n### Contribution Areas\n\n- \ud83e\udde0 **Memory System** - Enhance AI context retrieval\n- \ud83d\udd0d **Search** - Improve semantic search algorithms\n- \ud83c\udfa8 **Web UI** - Frontend improvements\n- \ud83d\udcdd **Documentation** - Guides and examples\n- \ud83d\udd0c **Integrations** - New IDE support\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\nFree to use, modify, and distribute in your projects.\n\n---\n\n## \ud83d\ude4f Built With\n\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** - IDE integration foundation\n- **[LanceDB](https://lancedb.com/)** - Embedded vector database for semantic search\n- **[FastAPI](https://fastapi.tiangolo.com/)** - High-performance Python web framework\n- **[Next.js](https://nextjs.org/)** - React framework for the web UI\n- **[Anthropic Claude](https://www.anthropic.com/)** - AI-powered intelligence\n\n---\n\n## \ud83d\ude80 Ready to Get Started?\n\n```bash\n# Fastest way - one command:\nuvx mcp-jive server --port 3454 --http\n\n# Or install with pip:\npip install mcp-jive && mcp-jive server --port 3454 --http\n\n# Then configure your IDE (see Quick Start above)\n```\n\n**Join developers using AI agents to build better software, faster.**\n\n---\n\n## \ud83d\udce6 Distribution & Installation\n\nFor more installation options including Docker, see [DISTRIBUTION.md](DISTRIBUTION.md)\n\n**Available on:**\n- \ud83d\udce6 PyPI: `pip install mcp-jive` or `uvx mcp-jive`\n- \ud83d\udc33 Docker: `docker run mcpjive/mcp-jive:latest` (coming soon)\n- \ud83d\udce5 Source: `git clone <repository-url>`\n\n---\n\n\ud83d\udcda [Documentation](docs/README.md) \u2022 \ud83d\udd27 [Contributing](CONTRIBUTING.md) \u2022 \ud83d\udce6 [Distribution Guide](DISTRIBUTION.md) \u2022 \ud83d\udcac [Discussions](https://github.com/your-repo/discussions) \u2022 \ud83d\udc1b [Issues](https://github.com/your-repo/issues)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered task and workflow management server implementing the Model Context Protocol (MCP)",
"version": "1.4.0",
"project_urls": {
"Documentation": "https://docs.mcpjive.com",
"Homepage": "https://github.com/mcpjive/mcp-jive",
"Issues": "https://github.com/mcpjive/mcp-jive/issues",
"Repository": "https://github.com/mcpjive/mcp-jive"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" ai",
" task-management",
" workflow",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "059d4866768a87de5aadc71bbf1370fe3169f7df03ca1aef2cd352e9132f4f73",
"md5": "1543b0fbb84d70eae8b1553310c0c014",
"sha256": "0d276757d2874387d52defa719ba01f4982490c8af146d9a591dc22e839309ad"
},
"downloads": -1,
"filename": "mcp_jive-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1543b0fbb84d70eae8b1553310c0c014",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 292814,
"upload_time": "2025-10-06T12:43:51",
"upload_time_iso_8601": "2025-10-06T12:43:51.417044Z",
"url": "https://files.pythonhosted.org/packages/05/9d/4866768a87de5aadc71bbf1370fe3169f7df03ca1aef2cd352e9132f4f73/mcp_jive-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ff97be8c4753d1f56ed44de1114cebea41180af317ad33ae9cd03df82d4d2c31",
"md5": "cf10341ae5637534eaf86bc380ac0fa8",
"sha256": "5494d4daf0bff51ed58065adf44ed9a8c1195ce8e8a3c9915a46b1570423d9a9"
},
"downloads": -1,
"filename": "mcp_jive-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "cf10341ae5637534eaf86bc380ac0fa8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 286518,
"upload_time": "2025-10-06T12:43:53",
"upload_time_iso_8601": "2025-10-06T12:43:53.014528Z",
"url": "https://files.pythonhosted.org/packages/ff/97/be8c4753d1f56ed44de1114cebea41180af317ad33ae9cd03df82d4d2c31/mcp_jive-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 12:43:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mcpjive",
"github_project": "mcp-jive",
"github_not_found": true,
"lcname": "mcp-jive"
}
JSON
