Initial commit

2025-11-30 08:49:50 +08:00
commit adc4b2be25
147 changed files with 24716 additions and 0 deletions
--- a/skills/mxcp-expert/assets/project-templates/jira-oauth/README.md
+++ b/skills/mxcp-expert/assets/project-templates/jira-oauth/README.md
@@ -0,0 +1,160 @@
+# Connect Jira to MXCP with OAuth
+
+This example shows how to connect JIRA to MXCP using secure OAuth authentication.
+
+## What You Get
+
+Once configured, you can query your Jira data directly from MXCP:
+
+```sql
+-- Find all issues assigned to you
+SELECT jql_query_jira('assignee = currentUser()') AS my_issues;
+
+-- Get recent bugs in a project
+SELECT jql_query_jira('project = MYPROJECT AND type = Bug AND created >= -7d') AS recent_bugs;
+
+-- List all your accessible projects
+SELECT list_projects_jira() AS projects;
+
+-- Get user information
+SELECT get_user_jira('john.doe@company.com') AS user_info;
+```
+
+## Quick Setup Guide
+
+### Step 1: Create Your OAuth App in Atlassian
+
+1. Go to [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/)
+2. Click **Create** → **OAuth 2.0 (3LO)**
+3. Fill in your app details:
+   - **App name**: `MXCP Jira Integration` (or whatever you prefer)
+   - **Description**: `OAuth integration for MXCP`
+4. Click **Create**
+
+### Step 2: Configure OAuth Settings
+
+After creating your app:
+
+1. Click on your newly created app
+2. Go to **Permissions** → **Add** → **Jira API**
+3. Add these scopes:
+   - `read:me` (to read your own profile information)
+   - `read:jira-work` (to read issues and projects)
+   - `read:jira-user` (to read user information)
+   - `offline_access` (to refresh tokens)
+
+4. Go to **Authorization** → **OAuth 2.0 (3LO)**
+5. Add your callback URL based on your deployment:
+   - **For production**: `https://your-domain.com/atlassian/callback`
+   - **For local development**: `http://localhost:8000/atlassian/callback`
+   - **For ngrok testing**: `https://your-ngrok-url.ngrok.io/atlassian/callback`
+
+6. **Important**: Save your **Client ID** and **Client Secret** - you'll need these next!
+
+### Step 3: Set Up Environment Variables
+
+Create a `.env` file or set these environment variables:
+
+```bash
+export ATLASSIAN_CLIENT_ID="your-client-id-here"
+export ATLASSIAN_CLIENT_SECRET="your-client-secret-here"
+```
+
+### Step 4: Configure MXCP
+
+This example includes a ready-to-use `config.yml` file that you can customize with your OAuth credentials. You can either:
+
+- **Use the included file**: Edit the existing `config.yml` in this directory
+- **Create your own**: Use the template below
+
+Configuration template:
+
+```yaml
+mxcp: 1.0.0
+transport:
+  http:
+    port: 8000
+    host: 0.0.0.0
+    # Set base_url to your server's public URL for production
+    base_url: http://localhost:8000
+
+projects:
+  my-jira-project:
+    profiles:
+      dev:
+        # OAuth Configuration
+        auth:
+          provider: atlassian
+          clients:
+            - client_id: "${ATLASSIAN_CLIENT_ID}"
+              client_secret: "${ATLASSIAN_CLIENT_SECRET}"
+              name: "MXCP Jira Integration"
+              redirect_uris:
+                # For production, use your actual domain (must match base_url above)
+                - "https://your-domain.com/atlassian/callback"
+                # For local development, uncomment the line below:
+                # - "http://localhost:8000/atlassian/callback"
+              scopes:
+                - "mxcp:access"
+          atlassian:
+            client_id: "${ATLASSIAN_CLIENT_ID}"
+            client_secret: "${ATLASSIAN_CLIENT_SECRET}"
+            scope: "read:me read:jira-work read:jira-user offline_access"
+            callback_path: "/atlassian/callback"
+            auth_url: "https://auth.atlassian.com/authorize"
+            token_url: "https://auth.atlassian.com/oauth/token"
+        
+        # Plugin Configuration (minimal setup required!)
+        plugin:
+          config:
+            jira_oauth: {}  # Named 'jira_oauth' here, but UDFs use 'jira' suffix from mxcp-site.yml
+```
+
+### Step 5: Install and Run
+
+1. **Install dependencies**:
+   ```bash
+   pip install atlassian-python-api requests
+   ```
+
+2. **Start MXCP**:
+   ```bash
+   # From the examples/jira-oauth directory:
+   MXCP_CONFIG=config.yml mxcp serve
+   ```
+
+3. **Authenticate**:
+   - Configure the MXCP server in your MCP client (e.g., Claude Desktop)
+   - When the client connects, you'll be redirected to Atlassian to authorize the app
+   - After authorization, you'll be redirected back to your MCP client
+   - You're now ready to query Jira!
+
+## Available Functions
+
+| Function | Description | Example |
+|----------|-------------|---------|
+| `jql_query_jira(query, start, limit)` | Execute JQL queries | `SELECT jql_query_jira('project = TEST')` |
+| `list_projects_jira()` | List all your accessible projects | `SELECT list_projects_jira()` |
+| `get_project_jira(key)` | Get details for a specific project | `SELECT get_project_jira('TEST')` |
+| `get_user_jira(username)` | Get user information | `SELECT get_user_jira('john@company.com')` |
+
+## Example Queries
+
+```sql
+-- Get your assigned issues
+SELECT jql_query_jira('assignee = currentUser() AND status != Done', 0, 20) AS my_open_issues;
+
+-- Find high priority bugs
+SELECT jql_query_jira('priority = High AND type = Bug', 0, 10) AS high_priority_bugs;
+
+-- Recent activity in a project
+SELECT jql_query_jira('project = MYPROJECT AND updated >= -3d') AS recent_activity;
+
+-- Get project information
+SELECT 
+    list_projects_jira() AS all_projects,
+    get_project_jira('MYPROJECT') AS project_details;
+
+-- Find issues by reporter
+SELECT jql_query_jira('reporter = "john.doe@company.com"') AS johns_issues;
+```