mirror of
https://github.com/samanhappy/mcphub.git
synced 2025-12-24 18:59:30 -05:00
Compare commits
4 Commits
copilot/fi
...
copilot/fi
| Author | SHA1 | Date | |
|---|---|---|---|
|
dc8ff4bedd | ||
|
|
29c1b332b6 | ||
|
|
8245195462 | ||
|
|
0de1eb6e69 |
@@ -57,15 +57,6 @@ Créez un fichier `mcp_settings.json` pour personnaliser les paramètres de votr
|
||||
}
|
||||
```
|
||||
|
||||
#### Exemples de Configuration
|
||||
|
||||
Pour des configurations spécifiques de serveurs MCP, consultez le répertoire [examples](./examples/) :
|
||||
|
||||
- **[Démarrage rapide Jira Cloud](./examples/QUICK_START_JIRA.md)** - Guide de configuration en 5 minutes pour Jira Cloud
|
||||
- **[Guide complet Atlassian/Jira](./examples/README_ATLASSIAN_JIRA.md)** - Configuration détaillée pour Jira et Confluence
|
||||
- **[Variables d'environnement](./examples/mcp_settings_with_env_vars.json)** - Utilisation de variables d'environnement dans la configuration
|
||||
- **[OpenAPI Schema](./examples/openapi-schema-config.json)** - Serveurs MCP basés sur OpenAPI
|
||||
|
||||
### Déploiement avec Docker
|
||||
|
||||
**Recommandé** : Montez votre configuration personnalisée :
|
||||
|
||||
@@ -59,15 +59,6 @@ Create a `mcp_settings.json` file to customize your server settings:
|
||||
}
|
||||
```
|
||||
|
||||
#### Configuration Examples
|
||||
|
||||
For specific MCP server configurations, see the [examples](./examples/) directory:
|
||||
|
||||
- **[Jira Cloud Quick Start](./examples/QUICK_START_JIRA.md)** - 5-minute setup guide for Jira Cloud
|
||||
- **[Atlassian/Jira Complete Guide](./examples/README_ATLASSIAN_JIRA.md)** - Detailed setup for Jira and Confluence
|
||||
- **[Environment Variables](./examples/mcp_settings_with_env_vars.json)** - Using environment variables in configuration
|
||||
- **[OpenAPI Schema](./examples/openapi-schema-config.json)** - OpenAPI-based MCP servers
|
||||
|
||||
#### OAuth Configuration (Optional)
|
||||
|
||||
MCPHub supports OAuth 2.0 for authenticating with upstream MCP servers. See the [OAuth feature guide](docs/features/oauth.mdx) for a full walkthrough. In practice you will run into two configuration patterns:
|
||||
|
||||
@@ -57,15 +57,6 @@ MCPHub 通过将多个 MCP（Model Context Protocol）服务器组织为灵活
|
||||
}
|
||||
```
|
||||
|
||||
#### 配置示例
|
||||
|
||||
有关特定 MCP 服务器配置，请参阅 [examples](./examples/) 目录：
|
||||
|
||||
- **[Jira Cloud 快速入门](./examples/QUICK_START_JIRA.md)** - Jira Cloud 5 分钟配置指南
|
||||
- **[Atlassian/Jira 完整指南](./examples/README_ATLASSIAN_JIRA.md)** - Jira 和 Confluence 详细设置
|
||||
- **[环境变量](./examples/mcp_settings_with_env_vars.json)** - 在配置中使用环境变量
|
||||
- **[OpenAPI Schema](./examples/openapi-schema-config.json)** - 基于 OpenAPI 的 MCP 服务器
|
||||
|
||||
#### OAuth 配置（可选）
|
||||
|
||||
MCPHub 支持通过 OAuth 2.0 访问上游 MCP 服务器。完整说明请参阅[《OAuth 功能指南》](docs/zh/features/oauth.mdx)。实际使用中通常会遇到两类配置：
|
||||
|
||||
@@ -207,55 +207,6 @@ MCPHub uses several configuration files:
|
||||
}
|
||||
```
|
||||
|
||||
### Productivity and Project Management
|
||||
|
||||
#### Atlassian (Jira & Confluence) Server
|
||||
|
||||
```json
|
||||
{
|
||||
"atlassian": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}",
|
||||
"--confluence-url=${CONFLUENCE_URL}",
|
||||
"--confluence-username=${CONFLUENCE_USERNAME}",
|
||||
"--confluence-token=${CONFLUENCE_TOKEN}"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Jira Cloud Only Configuration:**
|
||||
|
||||
```json
|
||||
{
|
||||
"jira": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Required Environment Variables:**
|
||||
- `JIRA_URL`: Your Jira Cloud URL (e.g., `https://your-company.atlassian.net`)
|
||||
- `JIRA_USERNAME`: Your Atlassian account email
|
||||
- `JIRA_TOKEN`: API token from [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
|
||||
- `CONFLUENCE_URL`: Your Confluence URL (e.g., `https://your-company.atlassian.net/wiki`)
|
||||
- `CONFLUENCE_USERNAME`: Your Confluence account email (often same as Jira)
|
||||
- `CONFLUENCE_TOKEN`: Confluence API token (can be same as Jira token for Cloud)
|
||||
|
||||
**Setup Guide:** See [examples/README_ATLASSIAN_JIRA.md](../../examples/README_ATLASSIAN_JIRA.md) for detailed setup instructions.
|
||||
|
||||
### Map and Location Services
|
||||
|
||||
#### Amap (高德地图) Server
|
||||
|
||||
182
docs/transport-event-handlers-fix.md
Normal file
182
docs/transport-event-handlers-fix.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Transport Event Handlers Fix
|
||||
|
||||
## Problem Statement
|
||||
|
||||
After adding SSE (Server-Sent Events) or Streamable HTTP protocol servers, the server status did not automatically update when connections failed or closed. The status remained "connected" even when the connection was lost.
|
||||
|
||||
## Root Cause
|
||||
|
||||
The MCP SDK provides `onclose` and `onerror` event handlers for all transport types (SSE, StreamableHTTP, and stdio), but the MCPHub implementation was not setting up these handlers. This meant that:
|
||||
|
||||
1. When a connection closed unexpectedly, the server status remained "connected"
|
||||
2. When transport errors occurred, the status was not updated
|
||||
3. Users could not see the actual connection state in the dashboard
|
||||
|
||||
## Solution
|
||||
|
||||
Added a `setupTransportEventHandlers()` helper function that:
|
||||
|
||||
1. Sets up `onclose` handler to update status to 'disconnected' when connections close
|
||||
2. Sets up `onerror` handler to update status and capture error messages
|
||||
3. Clears keep-alive ping intervals when connections fail
|
||||
4. Logs connection state changes for debugging
|
||||
|
||||
The handlers are set up in two places:
|
||||
|
||||
1. After successful initial connection in `initializeClientsFromSettings()`
|
||||
2. After reconnection in `callToolWithReconnect()`
|
||||
|
||||
## Changes Made
|
||||
|
||||
### File: `src/services/mcpService.ts`
|
||||
|
||||
#### New Function: `setupTransportEventHandlers()`
|
||||
|
||||
```typescript
|
||||
const setupTransportEventHandlers = (serverInfo: ServerInfo): void => {
|
||||
if (!serverInfo.transport) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Set up onclose handler to update status when connection closes
|
||||
serverInfo.transport.onclose = () => {
|
||||
console.log(`Transport closed for server: ${serverInfo.name}`);
|
||||
if (serverInfo.status === 'connected') {
|
||||
serverInfo.status = 'disconnected';
|
||||
serverInfo.error = 'Connection closed';
|
||||
}
|
||||
|
||||
// Clear keep-alive interval if it exists
|
||||
if (serverInfo.keepAliveIntervalId) {
|
||||
clearInterval(serverInfo.keepAliveIntervalId);
|
||||
serverInfo.keepAliveIntervalId = undefined;
|
||||
}
|
||||
};
|
||||
|
||||
// Set up onerror handler to update status on connection errors
|
||||
serverInfo.transport.onerror = (error: Error) => {
|
||||
console.error(`Transport error for server ${serverInfo.name}:`, error);
|
||||
if (serverInfo.status === 'connected') {
|
||||
serverInfo.status = 'disconnected';
|
||||
serverInfo.error = `Transport error: ${error.message}`;
|
||||
}
|
||||
|
||||
// Clear keep-alive interval if it exists
|
||||
if (serverInfo.keepAliveIntervalId) {
|
||||
clearInterval(serverInfo.keepAliveIntervalId);
|
||||
serverInfo.keepAliveIntervalId = undefined;
|
||||
}
|
||||
};
|
||||
|
||||
console.log(`Transport event handlers set up for server: ${serverInfo.name}`);
|
||||
};
|
||||
```
|
||||
|
||||
#### Integration Points
|
||||
|
||||
1. **Initial Connection** - Added call after successful connection:
|
||||
```typescript
|
||||
if (!dataError) {
|
||||
serverInfo.status = 'connected';
|
||||
serverInfo.error = null;
|
||||
|
||||
// Set up transport event handlers for connection monitoring
|
||||
setupTransportEventHandlers(serverInfo);
|
||||
|
||||
// Set up keep-alive ping for SSE connections
|
||||
setupKeepAlive(serverInfo, expandedConf);
|
||||
}
|
||||
```
|
||||
|
||||
2. **Reconnection** - Added call after reconnection succeeds:
|
||||
```typescript
|
||||
// Update server info with new client and transport
|
||||
serverInfo.client = client;
|
||||
serverInfo.transport = newTransport;
|
||||
serverInfo.status = 'connected';
|
||||
|
||||
// Set up transport event handlers for the new connection
|
||||
setupTransportEventHandlers(serverInfo);
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Automated Tests
|
||||
|
||||
All 169 existing tests pass, including:
|
||||
- Integration tests for SSE transport (`tests/integration/sse-service-real-client.test.ts`)
|
||||
- Integration tests for StreamableHTTP transport
|
||||
- Unit tests for MCP service functionality
|
||||
|
||||
### Manual Testing
|
||||
|
||||
To manually test the fix:
|
||||
|
||||
1. **Add an SSE server** to `mcp_settings.json`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"test-sse-server": {
|
||||
"type": "sse",
|
||||
"url": "http://localhost:9999/sse",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Start MCPHub**: `pnpm dev`
|
||||
|
||||
3. **Observe the behavior**:
|
||||
- Server will initially show as "connecting"
|
||||
- When connection fails (port 9999 not available), status will update to "disconnected"
|
||||
- Error message will show: "Transport error: ..." or "Connection closed"
|
||||
|
||||
4. **Test connection recovery**:
|
||||
- Start an MCP server on the configured URL
|
||||
- The status should update to "connected" when available
|
||||
- Stop the MCP server
|
||||
- The status should update back to "disconnected"
|
||||
|
||||
### StreamableHTTP Testing
|
||||
|
||||
1. **Add a StreamableHTTP server** to `mcp_settings.json`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"test-http-server": {
|
||||
"type": "streamable-http",
|
||||
"url": "http://localhost:9999/mcp",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Follow the same testing steps as SSE
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Accurate Status**: Server status now reflects actual connection state
|
||||
2. **Better UX**: Users can see when connections fail in real-time
|
||||
3. **Debugging**: Error messages help diagnose connection issues
|
||||
4. **Resource Management**: Keep-alive intervals are properly cleaned up on connection failures
|
||||
5. **Consistent Behavior**: All transport types (SSE, StreamableHTTP, stdio) now have proper event handling
|
||||
|
||||
## Compatibility
|
||||
|
||||
- **Backwards Compatible**: No breaking changes to existing functionality
|
||||
- **SDK Version**: Requires `@modelcontextprotocol/sdk` v1.20.2 or higher (current version in use)
|
||||
- **Node.js**: Compatible with all supported Node.js versions
|
||||
- **Transport Types**: Works with SSEClientTransport, StreamableHTTPClientTransport, and StdioClientTransport
|
||||
|
||||
Note: The `onclose` and `onerror` event handlers are part of the Transport interface in the MCP SDK and have been available since early versions. The current implementation has been tested with SDK v1.20.2.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements for the future:
|
||||
|
||||
1. Add automatic reconnection logic for transient failures
|
||||
2. Add connection health metrics (uptime, error count)
|
||||
3. Emit events for UI notifications when status changes
|
||||
4. Add configurable retry strategies per server
|
||||
@@ -1,18 +0,0 @@
|
||||
# Atlassian Jira Cloud Configuration Example
|
||||
# Copy this to your .env file and fill in your actual values
|
||||
|
||||
# Jira Configuration (Required)
|
||||
JIRA_URL=https://your-company.atlassian.net
|
||||
JIRA_USERNAME=your.email@company.com
|
||||
JIRA_TOKEN=your_jira_api_token_here
|
||||
|
||||
# Confluence Configuration (Optional - only if you want to use Confluence)
|
||||
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
|
||||
CONFLUENCE_USERNAME=your.email@company.com
|
||||
CONFLUENCE_TOKEN=your_confluence_api_token_here
|
||||
|
||||
# Notes:
|
||||
# 1. Get your API token from: https://id.atlassian.com/manage-profile/security/api-tokens
|
||||
# 2. For Atlassian Cloud, you can often use the same API token for both Jira and Confluence
|
||||
# 3. The username should be your Atlassian account email address
|
||||
# 4. Never commit your .env file to version control
|
||||
@@ -1,264 +0,0 @@
|
||||
# Atlassian/Jira Configuration Screenshot Guide
|
||||
|
||||
This guide shows what your configuration should look like at each step.
|
||||
|
||||
## 📋 Configuration File Structure
|
||||
|
||||
Your `mcp_settings.json` should look like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"jira": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
]
|
||||
}
|
||||
},
|
||||
"users": [
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "${ADMIN_PASSWORD_HASH}",
|
||||
"isAdmin": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Security Note:** The `password` field must contain a bcrypt hash, not plain text.
|
||||
|
||||
**To generate a bcrypt hash:**
|
||||
```bash
|
||||
node -e "console.log(require('bcrypt').hashSync('your-password', 10))"
|
||||
```
|
||||
|
||||
**⚠️ CRITICAL SECURITY:**
|
||||
- Never use default credentials in production
|
||||
- Always change the admin password before deploying
|
||||
- Store password hashes, never plain text passwords
|
||||
|
||||
## 📁 File Structure
|
||||
|
||||
Your project should have these files:
|
||||
|
||||
```
|
||||
mcphub/
|
||||
├── mcp_settings.json ← Your configuration file
|
||||
├── .env ← Your environment variables (DO NOT COMMIT!)
|
||||
├── data/ ← Database directory (auto-created)
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 🔐 Environment Variables (.env file)
|
||||
|
||||
```env
|
||||
# .env file content
|
||||
JIRA_URL=https://mycompany.atlassian.net
|
||||
JIRA_USERNAME=myemail@company.com
|
||||
JIRA_TOKEN=ATBBxxxxxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
## 🎯 Expected Dashboard View
|
||||
|
||||
After starting MCPHub, you should see:
|
||||
|
||||
### 1. Server List View
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ MCP Servers │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ✅ jira │
|
||||
│ Status: Connected │
|
||||
│ Type: stdio │
|
||||
│ Command: uvx mcp-atlassian │
|
||||
│ Tools: 15 available │
|
||||
│ │
|
||||
│ [View Details] [Restart] [Stop] │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. Server Details View
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Server: jira │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Status: ✅ Connected │
|
||||
│ Type: stdio │
|
||||
│ Command: uvx │
|
||||
│ │
|
||||
│ Available Tools: │
|
||||
│ • jira_search_issues │
|
||||
│ • jira_get_issue │
|
||||
│ • jira_list_projects │
|
||||
│ • jira_get_project │
|
||||
│ • ... and 11 more │
|
||||
│ │
|
||||
│ Logs: │
|
||||
│ [INFO] Successfully connected to Jira │
|
||||
│ [INFO] Loaded 15 tools │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3. Connection Endpoints
|
||||
|
||||
Once connected, your Jira server is available at:
|
||||
|
||||
| Endpoint | URL | Description |
|
||||
|----------|-----|-------------|
|
||||
| All Servers | `http://localhost:3000/mcp` | Access all configured MCP servers |
|
||||
| Jira Only | `http://localhost:3000/mcp/jira` | Direct access to Jira server |
|
||||
| SSE (Legacy) | `http://localhost:3000/sse/jira` | SSE endpoint for Jira |
|
||||
|
||||
## ✅ Success Indicators
|
||||
|
||||
You'll know the configuration is working when you see:
|
||||
|
||||
1. **✅ Green status indicator** next to the server name
|
||||
2. **"Connected" status** in the server details
|
||||
3. **Tool count showing** (e.g., "15 tools available")
|
||||
4. **No error messages** in the logs
|
||||
5. **Server responds** to health check requests
|
||||
|
||||
## ❌ Common Error Indicators
|
||||
|
||||
### Connection Failed
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ ❌ jira │
|
||||
│ Status: Disconnected │
|
||||
│ Error: Failed to start server │
|
||||
│ Last error: 401 Unauthorized │
|
||||
│ │
|
||||
│ Possible causes: │
|
||||
│ • Invalid API token │
|
||||
│ • Wrong username/email │
|
||||
│ • Incorrect Jira URL │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### UVX Not Found
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ ❌ jira │
|
||||
│ Status: Error │
|
||||
│ Error: Command not found: uvx │
|
||||
│ │
|
||||
│ Solution: Install UV │
|
||||
│ curl -LsSf https://astral.sh/uv/install.sh | sh │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Environment Variable Not Set
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ ⚠️ jira │
|
||||
│ Status: Configuration Error │
|
||||
│ Error: Environment variable JIRA_TOKEN not found │
|
||||
│ │
|
||||
│ Solution: Check your .env file │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🧪 Testing Your Configuration
|
||||
|
||||
### Test 1: Health Check
|
||||
```bash
|
||||
curl http://localhost:3000/api/health
|
||||
```
|
||||
|
||||
Expected response:
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"servers": {
|
||||
"jira": "connected"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Test 2: List Servers
|
||||
```bash
|
||||
curl http://localhost:3000/api/servers
|
||||
```
|
||||
|
||||
Expected response:
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"name": "jira",
|
||||
"status": "connected",
|
||||
"type": "stdio",
|
||||
"toolCount": 15
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Test 3: MCP Endpoint
|
||||
```bash
|
||||
curl http://localhost:3000/mcp/jira \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"method": "tools/list",
|
||||
"params": {}
|
||||
}'
|
||||
```
|
||||
|
||||
Expected response: List of available Jira tools
|
||||
|
||||
## 📊 Log Messages Explained
|
||||
|
||||
### Successful Startup
|
||||
```
|
||||
[INFO] Loading configuration from mcp_settings.json
|
||||
[INFO] Found 1 MCP server(s) to initialize
|
||||
[INFO] Starting server: jira
|
||||
[INFO] Executing: uvx mcp-atlassian --jira-url=https://...
|
||||
[INFO] Successfully connected client for server: jira
|
||||
[INFO] Successfully listed 15 tools for server: jira
|
||||
[INFO] ✅ Server jira is ready
|
||||
```
|
||||
|
||||
### Connection Issues
|
||||
```
|
||||
[ERROR] Failed to start server: jira
|
||||
[ERROR] Error: spawn uvx ENOENT
|
||||
[WARN] Server jira will retry in 5 seconds
|
||||
```
|
||||
|
||||
### Authentication Issues
|
||||
```
|
||||
[ERROR] Failed to connect to Jira
|
||||
[ERROR] HTTP 401: Unauthorized
|
||||
[ERROR] Please check your API token and credentials
|
||||
```
|
||||
|
||||
## 🔍 Debugging Steps
|
||||
|
||||
If your server shows as disconnected:
|
||||
|
||||
1. **Check logs** in the dashboard or console
|
||||
2. **Verify environment variables** are set correctly
|
||||
3. **Test manually** with uvx:
|
||||
```bash
|
||||
uvx mcp-atlassian --jira-url=https://your-company.atlassian.net --jira-username=your@email.com --jira-token=your_token
|
||||
```
|
||||
4. **Check network connectivity** to Jira
|
||||
5. **Verify API token** is still valid
|
||||
6. **Restart MCPHub** after making changes
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- [Quick Start Guide](./QUICK_START_JIRA.md)
|
||||
- [Complete Setup Guide](./README_ATLASSIAN_JIRA.md)
|
||||
- [MCPHub Documentation](https://docs.mcphubx.com/)
|
||||
- [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
|
||||
@@ -1,134 +0,0 @@
|
||||
# Quick Start: Jira Cloud Integration
|
||||
|
||||
This is a quick 5-minute setup guide for connecting MCPHub to Jira Cloud.
|
||||
|
||||
## ⚡ Quick Setup (5 minutes)
|
||||
|
||||
### Step 1: Get Your Jira API Token (2 minutes)
|
||||
|
||||
1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
|
||||
2. Click **"Create API token"**
|
||||
3. Label it "MCPHub Integration"
|
||||
4. **Copy the token** (you can't see it again!)
|
||||
|
||||
### Step 2: Find Your Jira URL (30 seconds)
|
||||
|
||||
Your Jira URL is what you see in your browser:
|
||||
- Example: `https://mycompany.atlassian.net`
|
||||
- ✅ Include: `https://` protocol
|
||||
- ❌ Don't include: trailing `/` or `/jira`
|
||||
|
||||
### Step 3: Create .env File (1 minute)
|
||||
|
||||
Create a `.env` file in your MCPHub root directory:
|
||||
|
||||
```bash
|
||||
JIRA_URL=https://mycompany.atlassian.net
|
||||
JIRA_USERNAME=myemail@company.com
|
||||
JIRA_TOKEN=paste_your_token_here
|
||||
```
|
||||
|
||||
Replace with your actual values!
|
||||
|
||||
### Step 4: Update mcp_settings.json (1 minute)
|
||||
|
||||
Add this to your `mcp_settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"jira": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Install UV & Start MCPHub (1 minute)
|
||||
|
||||
#### Install UV (if not already installed):
|
||||
|
||||
**macOS/Linux:**
|
||||
```bash
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```powershell
|
||||
irm https://astral.sh/uv/install.ps1 | iex
|
||||
```
|
||||
|
||||
#### Start MCPHub:
|
||||
|
||||
**With Docker:**
|
||||
```bash
|
||||
docker run -p 3000:3000 \
|
||||
--env-file .env \
|
||||
-v ./mcp_settings.json:/app/mcp_settings.json \
|
||||
samanhappy/mcphub
|
||||
```
|
||||
|
||||
**Without Docker:**
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Step 6: Verify Connection (30 seconds)
|
||||
|
||||
1. Open http://localhost:3000
|
||||
2. Login with default credentials (see [README_ATLASSIAN_JIRA.md](./README_ATLASSIAN_JIRA.md#verification) for credentials)
|
||||
|
||||
**⚠️ CRITICAL:** Immediately change the admin password through dashboard Settings → Users
|
||||
|
||||
3. Check dashboard - you should see "jira" server as "Connected" ✅
|
||||
|
||||
## 🎉 That's It!
|
||||
|
||||
You can now use Jira through MCPHub at:
|
||||
- All servers: `http://localhost:3000/mcp`
|
||||
- Jira only: `http://localhost:3000/mcp/jira`
|
||||
|
||||
## 🐛 Common Issues
|
||||
|
||||
### "uvx command not found"
|
||||
```bash
|
||||
# Install UV first (see Step 5)
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
### "401 Unauthorized"
|
||||
- Double-check your API token
|
||||
- Make sure username is your email
|
||||
- Try regenerating the API token
|
||||
|
||||
### Server shows "Disconnected"
|
||||
- Check logs for specific errors
|
||||
- Verify .env file is in the correct location
|
||||
- Ensure no trailing slashes in JIRA_URL
|
||||
|
||||
### "Downloading cryptography" errors
|
||||
- This is usually temporary
|
||||
- Wait and restart MCPHub
|
||||
- Check internet connection
|
||||
|
||||
## 📚 Need More Help?
|
||||
|
||||
See [README_ATLASSIAN_JIRA.md](./README_ATLASSIAN_JIRA.md) for the complete guide with:
|
||||
- Both Jira + Confluence setup
|
||||
- Detailed troubleshooting
|
||||
- Security best practices
|
||||
- Example use cases
|
||||
|
||||
## 🔒 Security Reminder
|
||||
|
||||
- ✅ Never commit `.env` to git
|
||||
- ✅ Keep API tokens secret
|
||||
- ✅ Rotate tokens regularly
|
||||
- ✅ Use different tokens for dev/prod
|
||||
@@ -1,233 +0,0 @@
|
||||
# MCPHub Configuration Examples
|
||||
|
||||
This directory contains example configurations for various MCP servers and use cases.
|
||||
|
||||
## 📁 Directory Contents
|
||||
|
||||
### Atlassian/Jira Configuration
|
||||
|
||||
| File | Description | Best For |
|
||||
|------|-------------|----------|
|
||||
| [QUICK_START_JIRA.md](./QUICK_START_JIRA.md) | 5-minute quick start guide | Getting started fast with Jira Cloud |
|
||||
| [README_ATLASSIAN_JIRA.md](./README_ATLASSIAN_JIRA.md) | Complete setup guide | Comprehensive setup with troubleshooting |
|
||||
| [CONFIGURATION_SCREENSHOT_GUIDE.md](./CONFIGURATION_SCREENSHOT_GUIDE.md) | Visual configuration guide | Understanding the dashboard and logs |
|
||||
| [mcp_settings_atlassian_jira.json](./mcp_settings_atlassian_jira.json) | Basic Jira configuration | Copy-paste configuration template |
|
||||
| [.env.atlassian.example](./.env.atlassian.example) | Environment variables template | Setting up credentials securely |
|
||||
|
||||
### General Configuration Examples
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [mcp_settings_with_env_vars.json](./mcp_settings_with_env_vars.json) | Environment variable examples for various server types (SSE, HTTP, stdio, OpenAPI) |
|
||||
| [openapi-schema-config.json](./openapi-schema-config.json) | OpenAPI-based MCP server configuration examples |
|
||||
|
||||
## 🚀 Quick Start Guides
|
||||
|
||||
### For Jira Cloud Users
|
||||
|
||||
**New to MCPHub?** Start here: [QUICK_START_JIRA.md](./QUICK_START_JIRA.md)
|
||||
|
||||
This 5-minute guide covers:
|
||||
- ✅ Getting your API token
|
||||
- ✅ Basic configuration
|
||||
- ✅ Starting MCPHub
|
||||
- ✅ Verifying connection
|
||||
|
||||
### For Experienced Users
|
||||
|
||||
**Need detailed setup?** See: [README_ATLASSIAN_JIRA.md](./README_ATLASSIAN_JIRA.md)
|
||||
|
||||
This comprehensive guide includes:
|
||||
- 📋 Both Jira and Confluence configuration
|
||||
- 🔧 Multiple installation methods (uvx, python, docker)
|
||||
- 🐛 Extensive troubleshooting section
|
||||
- 🔒 Security best practices
|
||||
- 💡 Example use cases
|
||||
|
||||
### Need Visual Guidance?
|
||||
|
||||
**Want to see what to expect?** Check: [CONFIGURATION_SCREENSHOT_GUIDE.md](./CONFIGURATION_SCREENSHOT_GUIDE.md)
|
||||
|
||||
This visual guide shows:
|
||||
- 📊 Expected dashboard views
|
||||
- ✅ Success indicators
|
||||
- ❌ Common error messages
|
||||
- 🧪 Test commands and expected outputs
|
||||
|
||||
## 📝 Configuration Templates
|
||||
|
||||
### Jira Cloud Only
|
||||
|
||||
Minimal configuration for Jira Cloud:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"jira": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Jira + Confluence
|
||||
|
||||
Combined configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"atlassian": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}",
|
||||
"--confluence-url=${CONFLUENCE_URL}",
|
||||
"--confluence-username=${CONFLUENCE_USERNAME}",
|
||||
"--confluence-token=${CONFLUENCE_TOKEN}"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file based on [.env.atlassian.example](./.env.atlassian.example):
|
||||
|
||||
```env
|
||||
JIRA_URL=https://your-company.atlassian.net
|
||||
JIRA_USERNAME=your.email@company.com
|
||||
JIRA_TOKEN=your_api_token_here
|
||||
```
|
||||
|
||||
## 🔐 Security Best Practices
|
||||
|
||||
1. **Never commit sensitive data**
|
||||
- ✅ Use `.env` files for credentials
|
||||
- ✅ Add `.env` to `.gitignore`
|
||||
- ✅ Use environment variable substitution: `${VAR_NAME}`
|
||||
|
||||
2. **Protect your API tokens**
|
||||
- ✅ Rotate tokens regularly
|
||||
- ✅ Use different tokens for dev/staging/prod
|
||||
- ✅ Revoke unused tokens immediately
|
||||
|
||||
3. **Secure your configuration**
|
||||
- ✅ Restrict file permissions on `.env` files
|
||||
- ✅ Use secrets management in production
|
||||
- ✅ Audit token usage regularly
|
||||
|
||||
## 🛠️ Common Use Cases
|
||||
|
||||
### Case 1: Development Environment
|
||||
|
||||
**Scenario**: Testing Jira integration locally
|
||||
|
||||
**Files needed**:
|
||||
- `mcp_settings_atlassian_jira.json` → Copy to `mcp_settings.json`
|
||||
- `.env.atlassian.example` → Copy to `.env` and fill in values
|
||||
|
||||
**Steps**:
|
||||
1. Copy template files
|
||||
2. Fill in your credentials
|
||||
3. Run `pnpm dev`
|
||||
|
||||
### Case 2: Production Deployment
|
||||
|
||||
**Scenario**: Deploying MCPHub with Jira to production
|
||||
|
||||
**Approach**:
|
||||
- Use environment variables in configuration
|
||||
- Store secrets in your deployment platform's secrets manager
|
||||
- Use Docker with environment file: `docker run --env-file .env ...`
|
||||
|
||||
### Case 3: Multiple Environments
|
||||
|
||||
**Scenario**: Separate dev, staging, prod configurations
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
.env.development
|
||||
.env.staging
|
||||
.env.production
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
# Development
|
||||
docker run --env-file .env.development ...
|
||||
|
||||
# Staging
|
||||
docker run --env-file .env.staging ...
|
||||
|
||||
# Production
|
||||
docker run --env-file .env.production ...
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Quick Diagnostics
|
||||
|
||||
| Symptom | Likely Cause | Quick Fix |
|
||||
|---------|--------------|-----------|
|
||||
| "uvx command not found" | UV not installed | Install UV: `curl -LsSf https://astral.sh/uv/install.sh | sh` |
|
||||
| "401 Unauthorized" | Wrong API token | Regenerate token at Atlassian settings |
|
||||
| Server "Disconnected" | Missing env vars | Check `.env` file exists and has values |
|
||||
| "Downloading cryptography" errors | Network/Python issue | Wait and retry, check internet connection |
|
||||
|
||||
### Detailed Troubleshooting
|
||||
|
||||
For comprehensive troubleshooting steps, see:
|
||||
- [README_ATLASSIAN_JIRA.md - Troubleshooting Section](./README_ATLASSIAN_JIRA.md#troubleshooting)
|
||||
- [CONFIGURATION_SCREENSHOT_GUIDE.md - Error Indicators](./CONFIGURATION_SCREENSHOT_GUIDE.md#-common-error-indicators)
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
### Official Documentation
|
||||
|
||||
- [MCPHub Documentation](https://docs.mcphubx.com/)
|
||||
- [MCPHub GitHub Repository](https://github.com/samanhappy/mcphub)
|
||||
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
|
||||
|
||||
### Atlassian Resources
|
||||
|
||||
- [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
|
||||
- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)
|
||||
- [Confluence Cloud REST API](https://developer.atlassian.com/cloud/confluence/rest/v2/)
|
||||
- [MCP Atlassian Server](https://github.com/sooperset/mcp-atlassian)
|
||||
|
||||
### Community Support
|
||||
|
||||
- [MCPHub Discord Community](https://discord.gg/qMKNsn5Q)
|
||||
- [GitHub Issues](https://github.com/samanhappy/mcphub/issues)
|
||||
- [GitHub Discussions](https://github.com/samanhappy/mcphub/discussions)
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Have a useful configuration example? We'd love to include it!
|
||||
|
||||
1. Create your example configuration
|
||||
2. Add documentation explaining the setup
|
||||
3. Submit a pull request to the repository
|
||||
|
||||
Example contributions:
|
||||
- Configuration for other MCP servers
|
||||
- Multi-server setup examples
|
||||
- Docker Compose configurations
|
||||
- Kubernetes deployment examples
|
||||
- CI/CD integration examples
|
||||
|
||||
## 📄 License
|
||||
|
||||
All examples in this directory are provided under the same license as MCPHub (Apache 2.0).
|
||||
|
||||
Feel free to use, modify, and distribute these examples as needed for your projects.
|
||||
@@ -1,319 +0,0 @@
|
||||
# Atlassian Jira Cloud MCP Server Configuration
|
||||
|
||||
This guide provides detailed instructions for configuring the MCP Atlassian server to connect to Jira Cloud in MCPHub.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Jira Cloud Account**: You need access to a Jira Cloud instance
|
||||
2. **API Token**: Generate an API token from your Atlassian account
|
||||
3. **Python/UV**: The mcp-atlassian server requires Python and `uvx` (UV package manager)
|
||||
|
||||
## Step 1: Generate Jira API Token
|
||||
|
||||
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
|
||||
2. Click **"Create API token"**
|
||||
3. Give it a label (e.g., "MCPHub Integration")
|
||||
4. Copy the generated token (you won't be able to see it again!)
|
||||
5. Save it securely
|
||||
|
||||
## Step 2: Get Your Jira Information
|
||||
|
||||
You'll need the following information:
|
||||
|
||||
- **JIRA_URL**: Your Jira Cloud URL (e.g., `https://your-company.atlassian.net`)
|
||||
- **JIRA_USERNAME**: Your Atlassian account email (e.g., `your.email@company.com`)
|
||||
- **JIRA_TOKEN**: The API token you generated in Step 1
|
||||
|
||||
## Step 3: Set Environment Variables
|
||||
|
||||
Create or update your `.env` file in the MCPHub root directory:
|
||||
|
||||
```bash
|
||||
# Jira Configuration
|
||||
JIRA_URL=https://your-company.atlassian.net
|
||||
JIRA_USERNAME=your.email@company.com
|
||||
JIRA_TOKEN=your_api_token_here
|
||||
```
|
||||
|
||||
**Important Security Note**: Never commit your `.env` file to version control. It should be listed in `.gitignore`.
|
||||
|
||||
## Step 4: Configure MCPHub
|
||||
|
||||
### Option 1: Using Environment Variables (Recommended)
|
||||
|
||||
Update your `mcp_settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"atlassian": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: Direct Configuration (Not Recommended)
|
||||
|
||||
If you prefer not to use environment variables (less secure):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"atlassian": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=https://your-company.atlassian.net",
|
||||
"--jira-username=your.email@company.com",
|
||||
"--jira-token=your_api_token_here"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 3: Jira Only (Without Confluence)
|
||||
|
||||
If you only want to use Jira and not Confluence:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"jira": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 4: Both Jira and Confluence
|
||||
|
||||
To use both Jira and Confluence, you'll need API tokens for both:
|
||||
|
||||
```bash
|
||||
# .env file
|
||||
JIRA_URL=https://your-company.atlassian.net
|
||||
JIRA_USERNAME=your.email@company.com
|
||||
JIRA_TOKEN=your_jira_api_token
|
||||
|
||||
CONFLUENCE_URL=https://your-company.atlassian.net/wiki
|
||||
CONFLUENCE_USERNAME=your.email@company.com
|
||||
CONFLUENCE_TOKEN=your_confluence_api_token
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"atlassian": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--confluence-url=${CONFLUENCE_URL}",
|
||||
"--confluence-username=${CONFLUENCE_USERNAME}",
|
||||
"--confluence-token=${CONFLUENCE_TOKEN}",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: For Atlassian Cloud, you can often use the same API token for both Jira and Confluence.
|
||||
|
||||
## Step 5: Install UV (if not already installed)
|
||||
|
||||
The mcp-atlassian server uses `uvx` to run. Install UV if you haven't already:
|
||||
|
||||
### On macOS/Linux:
|
||||
```bash
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
### On Windows:
|
||||
```powershell
|
||||
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
|
||||
```
|
||||
|
||||
### Using pip:
|
||||
```bash
|
||||
pip install uv
|
||||
```
|
||||
|
||||
## Step 6: Start MCPHub
|
||||
|
||||
### Using Docker:
|
||||
```bash
|
||||
docker run -p 3000:3000 \
|
||||
-v ./mcp_settings.json:/app/mcp_settings.json \
|
||||
-v ./data:/app/data \
|
||||
-e JIRA_URL="${JIRA_URL}" \
|
||||
-e JIRA_USERNAME="${JIRA_USERNAME}" \
|
||||
-e JIRA_TOKEN="${JIRA_TOKEN}" \
|
||||
samanhappy/mcphub
|
||||
```
|
||||
|
||||
### Using Development Mode:
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Using Production Mode:
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm start
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After starting MCPHub:
|
||||
|
||||
1. Open `http://localhost:3000` in your browser
|
||||
2. Log in with default credentials: `admin` / `admin123`
|
||||
|
||||
**⚠️ SECURITY WARNING:** Change the default admin password immediately in production!
|
||||
|
||||
**To change the password:**
|
||||
- Option 1: Use the dashboard after logging in (Settings → Users → Change Password)
|
||||
- Option 2: Generate a bcrypt hash and update `mcp_settings.json`:
|
||||
```bash
|
||||
node -e "console.log(require('bcrypt').hashSync('your-new-password', 10))"
|
||||
```
|
||||
|
||||
3. Check the dashboard to see if the Atlassian server is connected
|
||||
4. Look for the server status - it should show as "Connected" or "Running"
|
||||
5. Check the logs for any connection errors
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "uvx command not found"
|
||||
|
||||
**Solution**: Install UV as described in Step 5 above.
|
||||
|
||||
### Error: "Traceback (most recent call last): File ... mcp-atlassian"
|
||||
|
||||
This error usually indicates:
|
||||
1. Missing or incorrect API credentials
|
||||
2. Network connectivity issues
|
||||
3. Python dependency issues
|
||||
|
||||
**Solutions**:
|
||||
- Verify your API token is correct
|
||||
- Ensure your Jira URL doesn't have trailing slashes
|
||||
- Check that your username is the email address you use for Atlassian
|
||||
- Verify network connectivity to your Jira instance
|
||||
- Try regenerating your API token
|
||||
|
||||
### Error: "401 Unauthorized"
|
||||
|
||||
**Solution**:
|
||||
- Double-check your API token is correct
|
||||
- Ensure you're using the email address associated with your Atlassian account
|
||||
- Regenerate your API token if needed
|
||||
|
||||
### Error: "403 Forbidden"
|
||||
|
||||
**Solution**:
|
||||
- Check that your account has appropriate permissions in Jira
|
||||
- Verify your Jira administrator hasn't restricted API access
|
||||
|
||||
### Error: Downloading cryptography errors
|
||||
|
||||
**Solution**:
|
||||
- This is usually a transient network or Python package installation issue
|
||||
- Wait a moment and try restarting MCPHub
|
||||
- Ensure you have a stable internet connection
|
||||
- If the issue persists, try installing mcp-atlassian manually:
|
||||
```bash
|
||||
uvx mcp-atlassian --help
|
||||
```
|
||||
|
||||
### Server shows as "Disconnected"
|
||||
|
||||
**Solution**:
|
||||
1. Check MCPHub logs for specific error messages
|
||||
2. Verify all environment variables are set correctly
|
||||
3. Test the connection manually:
|
||||
```bash
|
||||
uvx mcp-atlassian \
|
||||
--jira-url=https://your-company.atlassian.net \
|
||||
--jira-username=your.email@company.com \
|
||||
--jira-token=your_token
|
||||
```
|
||||
|
||||
## Using the Jira MCP Server
|
||||
|
||||
Once connected, you can use the Jira MCP server to:
|
||||
|
||||
- **Search Issues**: Query Jira issues using JQL
|
||||
- **Read Issues**: Get detailed information about specific issues
|
||||
- **Access Projects**: List and retrieve project metadata
|
||||
- **View Comments**: Read issue comments and discussions
|
||||
- **Get Transitions**: Check available status transitions for issues
|
||||
|
||||
Access the server through:
|
||||
- **All servers**: `http://localhost:3000/mcp`
|
||||
- **Specific server**: `http://localhost:3000/mcp/atlassian`
|
||||
- **Server groups**: `http://localhost:3000/mcp/{group}` (if configured)
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [MCP Atlassian GitHub Repository](https://github.com/sooperset/mcp-atlassian)
|
||||
- [Atlassian API Token Documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/)
|
||||
- [Jira Cloud REST API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)
|
||||
- [MCPHub Documentation](https://docs.mcphubx.com/)
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. ✅ **Always use environment variables** for sensitive credentials
|
||||
2. ✅ **Never commit `.env` files** to version control
|
||||
3. ✅ **Rotate API tokens** regularly
|
||||
4. ✅ **Use separate tokens** for different environments (dev, staging, prod)
|
||||
5. ✅ **Restrict API token permissions** to only what's needed
|
||||
6. ✅ **Monitor token usage** in Atlassian account settings
|
||||
7. ✅ **Revoke unused tokens** immediately
|
||||
|
||||
## Example Use Cases
|
||||
|
||||
### Example 1: Search for Issues
|
||||
Query: "List all open bugs assigned to me"
|
||||
- Tool: `jira_search_issues`
|
||||
- JQL: `project = MYPROJECT AND status = Open AND assignee = currentUser() AND type = Bug`
|
||||
|
||||
### Example 2: Get Issue Details
|
||||
Query: "Show me details of issue PROJ-123"
|
||||
- Tool: `jira_get_issue`
|
||||
- Issue Key: `PROJ-123`
|
||||
|
||||
### Example 3: List Projects
|
||||
Query: "What Jira projects do I have access to?"
|
||||
- Tool: `jira_list_projects`
|
||||
|
||||
## Need Help?
|
||||
|
||||
If you're still experiencing issues:
|
||||
|
||||
1. Check the [MCPHub Discord community](https://discord.gg/qMKNsn5Q)
|
||||
2. Review [MCPHub GitHub Issues](https://github.com/samanhappy/mcphub/issues)
|
||||
3. Check [mcp-atlassian Issues](https://github.com/sooperset/mcp-atlassian/issues)
|
||||
4. Contact your Jira administrator for API access questions
|
||||
@@ -1,22 +0,0 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"atlassian": {
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"mcp-atlassian",
|
||||
"--jira-url=${JIRA_URL}",
|
||||
"--jira-username=${JIRA_USERNAME}",
|
||||
"--jira-token=${JIRA_TOKEN}"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
},
|
||||
"users": [
|
||||
{
|
||||
"username": "admin",
|
||||
"_comment": "Password must be a bcrypt hash. Generate with: node -e \"console.log(require('bcrypt').hashSync('your-password', 10))\"",
|
||||
"password": "${ADMIN_PASSWORD_HASH}",
|
||||
"isAdmin": true
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -136,6 +136,48 @@ const setupKeepAlive = (serverInfo: ServerInfo, serverConfig: ServerConfig): voi
|
||||
);
|
||||
};
|
||||
|
||||
// Helper function to clean up server resources on disconnection
|
||||
const cleanupServerResources = (serverInfo: ServerInfo): void => {
|
||||
// Clear keep-alive interval if it exists
|
||||
if (serverInfo.keepAliveIntervalId) {
|
||||
clearInterval(serverInfo.keepAliveIntervalId);
|
||||
serverInfo.keepAliveIntervalId = undefined;
|
||||
}
|
||||
};
|
||||
|
||||
// Helper function to set up transport event handlers for connection monitoring
|
||||
const setupTransportEventHandlers = (serverInfo: ServerInfo): void => {
|
||||
if (!serverInfo.transport) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Set up onclose handler to update status when connection closes
|
||||
serverInfo.transport.onclose = () => {
|
||||
console.log(`Transport closed for server: ${serverInfo.name}`);
|
||||
// Update status to disconnected if not already in a terminal state
|
||||
if (serverInfo.status === 'connected' || serverInfo.status === 'connecting') {
|
||||
serverInfo.status = 'disconnected';
|
||||
serverInfo.error = 'Connection closed';
|
||||
}
|
||||
|
||||
cleanupServerResources(serverInfo);
|
||||
};
|
||||
|
||||
// Set up onerror handler to update status on connection errors
|
||||
serverInfo.transport.onerror = (error: Error) => {
|
||||
console.error(`Transport error for server ${serverInfo.name}:`, error);
|
||||
// Update status to disconnected if not already in a terminal state
|
||||
if (serverInfo.status === 'connected' || serverInfo.status === 'connecting') {
|
||||
serverInfo.status = 'disconnected';
|
||||
serverInfo.error = `Transport error: ${error.message}`;
|
||||
}
|
||||
|
||||
cleanupServerResources(serverInfo);
|
||||
};
|
||||
|
||||
console.log(`Transport event handlers set up for server: ${serverInfo.name}`);
|
||||
};
|
||||
|
||||
export const initUpstreamServers = async (): Promise<void> => {
|
||||
// Initialize OAuth clients for servers with dynamic registration
|
||||
await initializeAllOAuthClients();
|
||||
@@ -440,6 +482,9 @@ const callToolWithReconnect = async (
|
||||
serverInfo.transport = newTransport;
|
||||
serverInfo.status = 'connected';
|
||||
|
||||
// Set up transport event handlers for the new connection
|
||||
setupTransportEventHandlers(serverInfo);
|
||||
|
||||
// Reload tools list after reconnection
|
||||
try {
|
||||
const tools = await client.listTools({}, serverInfo.options || {});
|
||||
@@ -714,6 +759,9 @@ export const initializeClientsFromSettings = async (
|
||||
serverInfo.status = 'connected';
|
||||
serverInfo.error = null;
|
||||
|
||||
// Set up transport event handlers for connection monitoring
|
||||
setupTransportEventHandlers(serverInfo);
|
||||
|
||||
// Set up keep-alive ping for SSE connections
|
||||
setupKeepAlive(serverInfo, expandedConf);
|
||||
} else {
|
||||
|
||||
Reference in New Issue
Block a user