@crypto512/jicon-mcp 2.1.0 → 2.2.0

package/README.md

@@ -34,7 +34,7 @@ Once configured, just ask in natural language:
 - *"What happened on project ACME this week?"* (Activity digest)
 - *"Create a task for implementing user authentication"*
 - *"Move PROJ-123 to Done and add a comment that it's deployed"*
-- *"Show me the current sprint's progress"*
+- *"Analyze the current sprint - any risks or blockers?"* (Sprint analysis)
 - *"Summarize recent discussions about authentication"* (Comment analysis)
 - *"Link PROJ-456 as blocking PROJ-789"*
 
@@ -140,6 +140,10 @@ All configuration is done through environment variables.
 | `JICON_CONFLUENCE_WRITE_HOME` | `true`\|`false` | `false` | Restrict Confluence writes to personal space |
 | `JICON_PLANTUML_SERVER_URL` | string | - | PlantUML server URL (e.g., `http://localhost:8080`) |
 | `JICON_MAX_OUTPUT` | number | `16000` | Maximum output characters |
+| `JICON_TRANSPORT` | `stdio`\|`http` | `stdio` | Transport mode (use `http` for containers) |
+| `JICON_HTTP_PORT` | number | `3000` | HTTP server port |
+| `JICON_HTTP_HOST` | string | `0.0.0.0` | HTTP bind address |
+| `JICON_HTTP_BASE_PATH` | string | `/mcp` | MCP endpoint path |
 
 **Note:** Tempo uses the same Jira credentials - no separate configuration needed.
 
@@ -224,20 +228,6 @@ PlantUML validation requires an external PlantUML server. If not configured, Pla
 
 You can use the public PlantUML server (`http://www.plantuml.com/plantuml`) or run your own with Docker: `docker run -d -p 8080:8080 plantuml/plantuml-server:jetty`.
 
-### PlantUML Include Expansion
-
-C4-PlantUML, AWS icons, and Azure diagrams require `!include` directives. By default, Jicon expands these includes client-side before validation and sending to Confluence.
-
-**Whitelisted URLs:**
-- `https://raw.githubusercontent.com/plantuml-stdlib/` - C4, Azure, Kubernetes, etc.
-- `https://raw.githubusercontent.com/plantuml/` - Official PlantUML stdlib
-- `https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/` - AWS icons
-
-**Disable include expansion** (if you encounter issues):
-```json
-{ "plantumlInclude": false }
-```
-
 ## Authentication
 
 ### Atlassian Cloud
@@ -261,6 +251,289 @@ C4-PlantUML, AWS icons, and Azure diagrams require `!include` directives. By def
 - **Tempo** (optional) Timesheets plugin
 - **PlantUML Server** (optional) External server for diagram validation
 
+## Docker Deployment
+
+Jicon supports two transport modes:
+
+| Mode | Use Case | Protocol |
+|------|----------|----------|
+| **stdio** (default) | Local usage with `npx`, Claude Desktop, Claude Code | Standard I/O |
+| **http** | Containers, Kubernetes, remote servers | HTTP with StreamableHTTP |
+
+For containerized deployments, use HTTP mode which exposes the MCP protocol over HTTP.
+
+### Running with Docker
+
+**1. Build the image:**
+
+```bash
+docker build -t jicon-mcp .
+```
+
+**2. Run the container:**
+
+```bash
+docker run -d -p 3000:3000 \
+  -e JIRA_URL=https://jira.example.com \
+  -e JIRA_API_TOKEN=your-api-token \
+  -e CONFLUENCE_URL=https://confluence.example.com \
+  -e CONFLUENCE_API_TOKEN=your-api-token \
+  --name jicon-mcp \
+  jicon-mcp
+```
+
+The container automatically uses HTTP transport (`JICON_TRANSPORT=http`).
+
+**3. Verify it's running:**
+
+```bash
+curl http://localhost:3000/health
+# Returns: {"status":"ok"}
+```
+
+### Running with Docker Compose
+
+**1. Create a `.env` file with your credentials:**
+
+```bash
+cat > .env << 'EOF'
+JIRA_URL=https://jira.example.com
+JIRA_API_TOKEN=your-api-token
+CONFLUENCE_URL=https://confluence.example.com
+CONFLUENCE_API_TOKEN=your-api-token
+EOF
+```
+
+**2. Start the service:**
+
+```bash
+docker-compose up -d
+```
+
+**3. View logs:**
+
+```bash
+docker-compose logs -f
+```
+
+### HTTP Transport Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JICON_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
+| `JICON_HTTP_PORT` | `3000` | HTTP server port |
+| `JICON_HTTP_HOST` | `0.0.0.0` | HTTP bind address |
+| `JICON_HTTP_BASE_PATH` | `/mcp` | MCP endpoint path |
+
+### HTTP Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check - returns `{"status":"ok"}` |
+| `/ready` | GET | Readiness check - returns `{"status":"ready"}` |
+| `/mcp` | ALL | MCP protocol endpoint (StreamableHTTP) |
+
+### Connecting MCP Clients
+
+Once the HTTP server is running, connect your MCP client to `http://localhost:3000/mcp`:
+
+```bash
+# Using MCP Inspector
+npx @modelcontextprotocol/inspector --url http://localhost:3000/mcp
+```
+
+### Running HTTP Mode Locally (without Docker)
+
+For development or testing, you can run HTTP mode directly:
+
+```bash
+# Using npm script
+npm run start:http
+
+# Or with environment variables
+JICON_TRANSPORT=http \
+  JIRA_URL=https://jira.example.com \
+  JIRA_API_TOKEN=your-token \
+  npm start
+```
+
+### Kubernetes Deployment
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: jicon-secrets
+type: Opaque
+stringData:
+  jira-url: "https://jira.example.com"
+  jira-token: "your-api-token"
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: jicon-mcp
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: jicon-mcp
+  template:
+    metadata:
+      labels:
+        app: jicon-mcp
+    spec:
+      containers:
+      - name: jicon-mcp
+        image: jicon-mcp:latest
+        ports:
+        - containerPort: 3000
+        env:
+        - name: JICON_TRANSPORT
+          value: "http"
+        - name: JIRA_URL
+          valueFrom:
+            secretKeyRef:
+              name: jicon-secrets
+              key: jira-url
+        - name: JIRA_API_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: jicon-secrets
+              key: jira-token
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 3000
+          initialDelaySeconds: 5
+          periodSeconds: 30
+        readinessProbe:
+          httpGet:
+            path: /ready
+            port: 3000
+          initialDelaySeconds: 5
+          periodSeconds: 10
+        resources:
+          requests:
+            memory: "128Mi"
+            cpu: "100m"
+          limits:
+            memory: "256Mi"
+            cpu: "500m"
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: jicon-mcp
+spec:
+  selector:
+    app: jicon-mcp
+  ports:
+  - port: 3000
+    targetPort: 3000
+```
+
+### LibreChat Integration
+
+[LibreChat](https://www.librechat.ai/) supports MCP servers via the `streamable-http` transport type. This allows LibreChat to connect to jicon running in a container.
+
+**Basic configuration in `librechat.yaml`:**
+
+```yaml
+mcpServers:
+  jicon:
+    type: streamable-http
+    url: http://jicon-mcp:3000/mcp
+    timeout: 60000
+    initTimeout: 10000
+    serverInstructions: |
+      Jicon MCP server provides access to Jira, Confluence, and Tempo.
+      Use jicon_help tool to learn about available workflows.
+```
+
+**With environment variables for credentials:**
+
+Jicon reads credentials from its own environment variables. When running with Docker Compose, pass them to the jicon container:
+
+```yaml
+# docker-compose.yml
+version: "3.8"
+
+services:
+  jicon-mcp:
+    build: .
+    environment:
+      - JICON_TRANSPORT=http
+      - JIRA_URL=${JIRA_URL}
+      - JIRA_API_TOKEN=${JIRA_API_TOKEN}
+      - CONFLUENCE_URL=${CONFLUENCE_URL}
+      - CONFLUENCE_API_TOKEN=${CONFLUENCE_API_TOKEN}
+      - JICON_PERMISSIONS_MODE=${JICON_PERMISSIONS_MODE:-readonly}
+
+  librechat:
+    image: ghcr.io/danny-avila/librechat:latest
+    depends_on:
+      - jicon-mcp
+    volumes:
+      - ./librechat.yaml:/app/librechat.yaml
+    # ... other LibreChat configuration
+```
+
+**Per-user credentials with `customUserVars`:**
+
+Each LibreChat user can use their own Jira/Confluence credentials via HTTP headers. Configure `customUserVars` in LibreChat to prompt users for their credentials:
+
+```yaml
+# librechat.yaml
+mcpServers:
+  jicon:
+    type: streamable-http
+    url: http://jicon-mcp:3000/mcp
+    timeout: 60000
+    initTimeout: 10000
+    headers:
+      X-Jira-Url: "{{JIRA_URL}}"
+      X-Jira-Token: "{{JIRA_TOKEN}}"
+      X-Confluence-Url: "{{CONFLUENCE_URL}}"
+      X-Confluence-Token: "{{CONFLUENCE_TOKEN}}"
+    customUserVars:
+      JIRA_URL:
+        title: "Jira URL"
+        description: "Your Jira instance URL (e.g., https://jira.example.com)"
+      JIRA_TOKEN:
+        title: "Jira Token"
+        description: "Your Jira Personal Access Token"
+      CONFLUENCE_URL:
+        title: "Confluence URL"
+        description: "Your Confluence instance URL"
+      CONFLUENCE_TOKEN:
+        title: "Confluence Token"
+        description: "Your Confluence Personal Access Token"
+    serverInstructions: |
+      Jicon MCP server provides access to Jira, Confluence, and Tempo.
+      Use jicon_help tool to learn about available workflows.
+```
+
+**Per-user credential headers:**
+
+| Header | Description |
+|--------|-------------|
+| `X-Jira-Url` | Jira instance URL |
+| `X-Jira-Token` | Jira API token (PAT) |
+| `X-Confluence-Url` | Confluence instance URL |
+| `X-Confluence-Token` | Confluence API token (PAT) |
+
+Both URL and Token headers must be provided together for each service. Per-request credentials take priority over environment variables.
+
+**Timeout recommendations:**
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| `timeout` | `60000` | Request timeout (60s) - allows for large searches |
+| `initTimeout` | `10000` | Initialization timeout (10s) - jicon starts quickly |
+
+For more details, see [LibreChat MCP documentation](https://www.librechat.ai/docs/features/mcp).
+
 ## API Limitations
 
 ### Confluence Draft Limitations (Data Center REST API)