@mohammadhprp/system-prompt 0.12.1 → 0.12.2

package/framework/mcps/gitlab-mcp/troubleshooting.md

@@ -1,116 +0,0 @@
-# GitLab MCP Troubleshooting
-
-## Server won't start
-
-**Problem**
-
-The AI client reports that `gitlab` failed to start.
-
-**Cause**
-
-The client cannot run `zereight-mcp-gitlab`, Node.js is not installed, or the npm package is not installed globally.
-
-**Solution**
-
-- Run `zereight-mcp-gitlab` manually to verify the server starts.
-- Check Node.js is installed: `node --version` (requires >= 18).
-- Run `npm install -g @zereight/mcp-gitlab` to install globally.
-- If no global install, use `command: "npx"` with `args: ["-y", "@zereight/mcp-gitlab"]` instead.
-
-## Authentication errors
-
-**Problem**
-
-The server starts but returns authentication errors on tool calls.
-
-**Cause**
-
-The Personal Access Token is missing, expired, or has insufficient scopes.
-
-**Solution**
-
-- Verify the token is set in `GITLAB_PERSONAL_ACCESS_TOKEN` or passed via `--token`.
-- Confirm the token has the required scopes (`api` for full access, `read_api` for read-only).
-- Generate a new token in GitLab: **Settings → Access Tokens → Personal Access Tokens**.
-- Confirm the API URL is correct: `https://gitlab.com/api/v4` (SaaS) or `https://your-instance/api/v4` (self-hosted).
-
-## Configuration errors
-
-**Problem**
-
-The MCP server is not listed, or the client ignores the config file.
-
-**Cause**
-
-The config file is in the wrong location, the JSON is invalid, or the client expects a different configuration wrapper.
-
-**Solution**
-
-- Validate the JSON with `python -m json.tool <file>` or another JSON parser.
-- Confirm the client-specific config location in the client's documentation.
-- Keep the server name as `gitlab`.
-- Ensure environment variables are set correctly in the config.
-
-## Permission errors
-
-**Problem**
-
-Tools return 403 Forbidden or insufficient permissions.
-
-**Cause**
-
-The authenticated user does not have the required GitLab project or group permissions.
-
-**Solution**
-
-- Verify the user has at least Developer role in the target project or group.
-- Check if the project is in a subgroup that inherits different permissions.
-- Use `list_projects` to confirm which projects the token can access.
-
-## Rate limiting
-
-**Problem**
-
-Tools return 429 Too Many Requests errors.
-
-**Cause**
-
-GitLab API rate limits have been exceeded.
-
-**Solution**
-
-- Reduce the frequency of tool calls.
-- For self-hosted GitLab, check `gitlab.rb` rate limit settings.
-- Wait for the rate limit window to reset before retrying.
-
-## Version mismatch
-
-**Problem**
-
-Some tools are missing or behave differently than documented.
-
-**Cause**
-
-The installed npm package version is outdated.
-
-**Solution**
-
-- Update to the latest version: `npm update -g @zereight/mcp-gitlab`.
-- Check the installed version: `npm list -g @zereight/mcp-gitlab`.
-- Refer to the [CHANGELOG](https://github.com/zereight/gitlab-mcp/blob/main/CHANGELOG.md) for breaking changes.
-
-## Read-only mode blocking writes
-
-**Problem**
-
-Write tools return errors when `GITLAB_PERMISSION_MODE=readonly`.
-
-**Cause**
-
-Read-only mode explicitly blocks all create, update, and delete operations.
-
-**Solution**
-
-- Set `GITLAB_PERMISSION_MODE=modify` to allow updates while blocking deletes.
-- Set `GITLAB_PERMISSION_MODE=full` for unrestricted access.
-- Use `GITLAB_TOOLS` allow-list to enable specific write tools in read-only mode.

package/framework/mcps/jira-mcp/README.md

@@ -1,52 +0,0 @@
-# Jira MCP
-
-## Overview
-
-Jira MCP is a Model Context Protocol (MCP) server for interacting with self-hosted Jira instances using Personal Access Token (PAT) authentication. It provides tools for creating, reading, updating, and deleting issues, searching with JQL, managing comments and assignments, and inspecting projects.
-
-Official source:
-
-- [GitHub: edrich13/mcp-jira-server](https://github.com/edrich13/mcp-jira-server)
-
-## Features
-
-- Personal Access Token authentication for self-hosted Jira.
-- Create, read, update, and delete Jira issues.
-- Search issues using JQL (Jira Query Language).
-- Add and view comments.
-- Manage issue assignments.
-- List projects and issue types.
-- Transition issues between statuses.
-- Get current user information.
-
-## Supported AI Clients
-
-Jira MCP works with any MCP-compatible AI client. The server is started via `npx` and communicates over stdio.
-
-- OpenCode
-
-## When to Use
-
-Use Jira MCP when an AI coding agent needs to interact with a self-hosted Jira instance.
-
-Good fits:
-
-- Creating and updating Jira issues from an AI agent.
-- Searching for issues with JQL queries.
-- Adding comments and managing issue assignments.
-- Inspecting project metadata and issue types.
-- Tracking work and status transitions.
-
-Avoid using it with Jira Cloud (SaaS) — this server is designed for self-hosted Jira instances only.
-
-## Requirements
-
-- Node.js 18 or higher available on `PATH`.
-- A self-hosted Jira instance (e.g., `https://jira.domain.com`).
-- A Jira Personal Access Token with appropriate permissions.
-
-## Related Skills
-
-Relevant skills in this repository:
-
-- [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for debugging and testing.

package/framework/mcps/jira-mcp/capabilities.md

@@ -1,79 +0,0 @@
-# Jira MCP Capabilities
-
-## What It Can Do
-
-12 tools for interacting with self-hosted Jira instances.
-
-### Issues
-
-| Tool | Description |
-| --- | --- |
-| `jira_get_issue` | Get details of a specific issue by key (e.g. "PROJ-123") |
-| `jira_search_issues` | Search for issues using JQL with optional max results |
-| `jira_create_issue` | Create a new issue with project, summary, type, description, priority, assignee, labels, components, and custom fields |
-| `jira_update_issue` | Update an existing issue — summary, description, assignee, priority, labels, status, and custom fields |
-| `jira_delete_issue` | Delete an issue permanently |
-| `jira_assign_issue` | Assign an issue to a user |
-
-### Comments
-
-| Tool | Description |
-| --- | --- |
-| `jira_add_comment` | Add a comment to an issue |
-| `jira_get_comments` | Get all comments from an issue |
-
-### Projects
-
-| Tool | Description |
-| --- | --- |
-| `jira_get_projects` | List all available projects |
-| `jira_get_project` | Get details of a specific project |
-| `jira_get_issue_types` | Get available issue types for a project |
-
-### User
-
-| Tool | Description |
-| --- | --- |
-| `jira_get_current_user` | Get information about the currently authenticated user |
-
-## What It Cannot Do
-
-- It does not work with Jira Cloud (SaaS) — designed for self-hosted instances only.
-- It cannot authenticate with OAuth, API tokens, or cookie-based auth — PAT only.
-- It cannot create, update, or delete Jira projects.
-- It cannot manage Jira users, groups, or permissions.
-- It cannot access Jira boards, sprints, or agile features.
-- It cannot attach files to issues.
-- It cannot operate without a valid PAT and accessible Jira instance.
-
-## Best Practices
-
-- Never commit your PAT to version control. Use environment variables or client config files with restricted permissions.
-- Use tokens with minimal required permissions.
-- Set expiration dates for tokens and rotate them regularly.
-- Use `jira_get_issue_types` before creating issues to confirm valid types for the project.
-- Use `jira_get_current_user` first to verify authentication is working.
-- Use JQL with specific project keys to scope searches and reduce response size.
-- For Jira instances behind SSO proxies, set `JIRA_USER_AGENT` to a whitelisted value.
-
-## Common Workflows
-
-### Find and update issues
-
-1. Call `jira_search_issues` with a JQL query to find relevant issues.
-2. Call `jira_get_issue` on a specific key to read full details.
-3. Call `jira_update_issue` to change status, assignee, or priority.
-4. Call `jira_add_comment` to leave a note about the change.
-
-### Create a new issue
-
-1. Call `jira_get_projects` to list available projects.
-2. Call `jira_get_issue_types` for the target project.
-3. Call `jira_create_issue` with project key, summary, issue type, and optional fields.
-4. Call `jira_assign_issue` to assign it to a team member.
-
-### Track work progress
-
-1. Call `jira_search_issues` with `assignee = currentUser() AND status != Done`.
-2. Call `jira_get_issue` on each key to review details.
-3. Call `jira_update_issue` to transition statuses as work progresses.

package/framework/mcps/jira-mcp/configs/.env.example

@@ -1,2 +0,0 @@
-JIRA_BASE_URL=
-JIRA_PAT=

package/framework/mcps/jira-mcp/configs/opencode.json

@@ -1,13 +0,0 @@
-{
-  "mcp": {
-    "jira": {
-      "type": "local",
-      "enabled": true,
-      "command": ["npx", "-y", "mcp-jira-server"],
-      "environment": {
-        "JIRA_BASE_URL": "{env:JIRA_BASE_URL}",
-        "JIRA_PAT": "{env:JIRA_PAT}"
-      }
-    }
-  }
-}

package/framework/mcps/jira-mcp/install.md

@@ -1,94 +0,0 @@
-# Jira MCP Installation
-
-## Requirements
-
-- Node.js 18 or higher available on `PATH`.
-- A self-hosted Jira instance.
-- A Jira Personal Access Token.
-- An MCP-compatible AI client.
-
-## Creating a Personal Access Token
-
-1. Log in to your self-hosted Jira instance.
-2. Click your profile icon → **Profile** or **Account Settings**.
-3. Navigate to **Personal Access Tokens** or **Security**.
-4. Click **Create token**, give it a name, set an expiration date, and copy the token immediately.
-
-## Installation
-
-The server can be used directly with `npx` — no build step required.
-
-```bash
-npx -y mcp-jira-server
-```
-
-Or install globally:
-
-```bash
-npm install -g mcp-jira-server
-```
-
-## Configuration
-
-| Field | Value |
-| --- | --- |
-| Server name | `jira` |
-| Command | `npx` (or `mcp-jira-server` if installed globally) |
-| Args | `-y`, `mcp-jira-server` |
-| Env | `JIRA_BASE_URL`, `JIRA_PAT` |
-
-### Config file examples
-
-Use the examples in [`configs/`](./configs/) as client-specific starting points:
-
-| Client | Example | Typical location |
-| --- | --- | --- |
-| OpenCode | [`configs/opencode.json`](./configs/opencode.json) | OpenCode MCP configuration. |
-
-### OpenCode
-
-Copy [`configs/opencode.json`](./configs/opencode.json) into your OpenCode project root or user config directory, replace the placeholder URL and token, and restart the OpenCode agent.
-
-## Verification
-
-Run the MCP server command directly:
-
-```bash
-npx -y mcp-jira-server
-```
-
-Then verify from your AI client:
-
-- The `jira` MCP server is listed.
-- The server starts without errors.
-- Tools are visible to the agent.
-
-Recommended first prompt:
-
-```
-Get my current Jira user information
-```
-
-## Updating
-
-```bash
-npx -y mcp-jira-server@latest
-```
-
-Or update global install:
-
-```bash
-npm update -g mcp-jira-server
-```
-
-## Uninstalling
-
-1. Remove the MCP entry from AI client configuration files.
-2. Uninstall the package: `npm uninstall -g mcp-jira-server`.
-
-## Common Issues
-
-- **Server does not start**: run `npx -y mcp-jira-server` manually. Ensure Node.js >= 18 is installed.
-- **Authentication errors**: verify the PAT is valid and not expired. Confirm `JIRA_BASE_URL` has no trailing slash.
-- **Connection refused**: check if the Jira instance is accessible and the URL is correct.
-- **API requests redirect to SSO login**: your Jira may be behind a reverse proxy. Set `JIRA_USER_AGENT` to a whitelisted User-Agent string.

package/framework/mcps/jira-mcp/troubleshooting.md

@@ -1,113 +0,0 @@
-# Jira MCP Troubleshooting
-
-## Server won't start
-
-**Problem**
-
-The AI client reports that `jira` failed to start.
-
-**Cause**
-
-The client cannot run `npx`, Node.js is not installed, or the npm package is unavailable.
-
-**Solution**
-
-- Run `npx -y mcp-jira-server` manually to verify the server starts.
-- Check Node.js is installed: `node --version` (requires >= 18).
-- Check network access if the package has not been cached locally.
-- Ensure the config file contains the correct command and args.
-
-## Authentication errors
-
-**Problem**
-
-The server starts but returns authentication errors on tool calls.
-
-**Cause**
-
-The Personal Access Token is missing, expired, or has insufficient permissions.
-
-**Solution**
-
-- Verify `JIRA_PAT` is set correctly in the environment.
-- Confirm the token has not expired.
-- Generate a new token in Jira if needed.
-- Verify `JIRA_BASE_URL` is correct and has no trailing slash.
-
-## Connection refused
-
-**Problem**
-
-Tools return connection errors.
-
-**Cause**
-
-The Jira instance is not accessible from the current machine.
-
-**Solution**
-
-- Verify the Jira URL is reachable: `curl https://jira.domain.com`.
-- Check network connectivity and firewall rules.
-- Confirm the URL format: `https://jira.domain.com` (no trailing slash).
-
-## Configuration errors
-
-**Problem**
-
-The MCP server is not listed, or the client ignores the config file.
-
-**Cause**
-
-The config file is in the wrong location, the JSON is invalid, or the client expects a different configuration wrapper.
-
-**Solution**
-
-- Validate the JSON with `python -m json.tool <file>` or another JSON parser.
-- Confirm the client-specific config location in the client's documentation.
-- Keep the server name as `jira`.
-- Ensure environment variables are set correctly in the config.
-
-## API requests redirect to SSO login
-
-**Problem**
-
-API requests return HTML login pages instead of JSON responses despite a valid PAT.
-
-**Cause**
-
-The Jira instance is behind a reverse proxy (oauth2-proxy, nginx, etc.) that filters requests by User-Agent and redirects API clients to SSO login.
-
-**Solution**
-
-- Set the `JIRA_USER_AGENT` environment variable to a whitelisted User-Agent string.
-- Contact your system administrator to get the allowed User-Agent value.
-
-## "Issue type not found" errors
-
-**Problem**
-
-Creating an issue fails with "issue type not found".
-
-**Cause**
-
-The issue type name does not exist in the target project.
-
-**Solution**
-
-- Call `jira_get_issue_types` with the project key to list valid types.
-- Use an exact match from the returned list.
-
-## "Cannot find module" errors
-
-**Problem**
-
-The server fails with module resolution errors when using a source build.
-
-**Cause**
-
-Dependencies are not installed or the project is not built.
-
-**Solution**
-
-- Run `npm install` and `npm run build` in the project directory.
-- Use the `npx` command instead of a local build.

package/framework/skills/gitlab-mcp/SKILL.md

@@ -1,83 +0,0 @@
----
-name: gitlab-mcp
-description: Use this skill when working with the GitLab MCP server tools for merge requests, issues, repositories, pipelines, work items, webhooks, search, and related GitLab workflows.
----
-
-# gitlab-mcp
-
-GitLab MCP server providing 173 tools: 171 tools across 16 toolsets, plus `execute_graphql` and the always-available `discover_tools` meta-tool.
-
-## Toolsets
-
-| Toolset                   | Default | Enable with                                          |
-|---------------------------|---------|------------------------------------------------------|
-| merge_requests (41 tools) | yes     | -                                                    |
-| issues (23 tools)         | yes     | -                                                    |
-| repositories (7 tools)    | yes     | -                                                    |
-| branches (6 tools)        | yes     | -                                                    |
-| projects (8 tools)        | yes     | -                                                    |
-| labels (5 tools)          | yes     | -                                                    |
-| ci (2 tools)              | yes     | -                                                    |
-| users (5 tools)           | yes     | -                                                    |
-| pipelines (19 tools)      | no      | `USE_PIPELINE=true` or `GITLAB_TOOLSETS=pipelines`   |
-| milestones (9 tools)      | no      | `USE_MILESTONE=true` or `GITLAB_TOOLSETS=milestones` |
-| wiki (10 tools)           | no      | `USE_GITLAB_WIKI=true` or `GITLAB_TOOLSETS=wiki`     |
-| releases (7 tools)        | no      | `GITLAB_TOOLSETS=releases`                           |
-| tags (5 tools)            | no      | `GITLAB_TOOLSETS=tags`                               |
-| workitems (18 tools)      | no      | `GITLAB_TOOLSETS=workitems`                          |
-| webhooks (3 tools)        | no      | `GITLAB_TOOLSETS=webhooks`                           |
-| search (3 tools)          | no      | `GITLAB_TOOLSETS=search`                             |
-
-Enable all: `GITLAB_TOOLSETS=all`. Use `GITLAB_TOOLS` to enable individual tools outside their toolset. `discover_tools` can activate opt-in categories for the current session.
-
-## Key Workflows
-
-### Code Review (see references/code-review.md)
-
-1. `list_merge_request_changed_files` - get file paths only (no diffs)
-2. `get_merge_request_file_diff` - get diffs for 3-5 files per call (batch)
-3. `create_merge_request_thread` or `create_draft_note` - leave review comments
-4. `bulk_publish_draft_notes` - publish all drafts at once
-
-### MR Lifecycle (see references/merge-requests.md)
-
-`create_merge_request` -> review -> `approve_merge_request` -> `merge_merge_request`
-
-### Issue Management (see references/issues.md)
-
-`create_issue` -> `create_issue_link` -> `create_issue_note` -> `update_issue`
-
-### Work Items (see references/work-items.md)
-
-`list_work_items` -> `get_work_item` -> `update_work_item` -> `create_work_item_note`
-
-### Webhooks & Search
-
-- Webhooks: see references/webhooks.md
-- Code search: see references/search.md
-
-### File Operations
-
-- Read: `get_file_contents`, `get_repository_tree`
-- Write: `create_or_update_file` (single file), `push_files` (multiple files in one commit)
-
-## Parameter Hints
-
-- **project_id**: numeric ID or URL-encoded path (`group/subgroup/project`)
-- **MR lookup**: provide `mergeRequestIid` OR `branchName` (not both)
-- **list_issues**: default scope = created by current user. Use `scope: "all"` for all issues
-- **list_merge_requests**: without project_id returns user's MRs across all projects
-- **emoji reactions**: merge request, issue, and work item reaction tools use GitLab emoji names like `thumbsup`, `rocket`, or `eyes`
-- **work items**: status and custom fields require GitLab Premium/Ultimate features
-- **execute_graphql**: escape double quotes in query strings
-
-## Destructive Tools (require caution)
-
-`delete_issue`, `delete_label`, `delete_wiki_page`, `delete_group_wiki_page`, `delete_milestone`, `delete_release`, `delete_tag`, `delete_merge_request_note`, `delete_merge_request_discussion_note`, `delete_draft_note`, `delete_issue_link`, `delete_merge_request_emoji_reaction`, `delete_merge_request_note_emoji_reaction`, `delete_issue_emoji_reaction`, `delete_issue_note_emoji_reaction`, `delete_work_item_emoji_reaction`, `delete_work_item_note_emoji_reaction`, `merge_merge_request`, `push_files`
-
-## Advanced
-
-- **Dynamic discovery**: `discover_tools` lists and activates opt-in toolsets at runtime
-- **GraphQL**: `execute_graphql` for queries not covered by REST tools
-- **Zoekt search**: `search_code`, `search_project_code`, `search_group_code` (requires advanced search enabled)
-- **Work Items**: GraphQL-based alternative to issues (Premium/Ultimate features)

package/framework/skills/gitlab-mcp/examples.md

@@ -1,31 +0,0 @@
-# GitLab MCP Examples
-
-## Example 1: Review Merge Request Diffs
-
-Review a merge request with multiple file changes. Good agent behavior:
-
-- Use `list_merge_request_changed_files` to get the list of changed files (no diff).
-- Use `get_merge_request_file_diff` with 3-5 files at a time to review diffs in batches.
-- Use `get_merge_request_approval_state` to check who has approved.
-- Use `create_merge_request_thread` to leave inline feedback on specific lines.
-- Use `approve_merge_request` and `merge_merge_request` when the review passes.
-
-## Example 2: Investigate Pipeline Failure
-
-A CI pipeline failed on the main branch. Good agent behavior:
-
-- Use `list_pipelines` to find the latest failed pipeline for the target branch.
-- Use `list_pipeline_jobs` to identify which job failed.
-- Use `get_pipeline_job_output` with pagination to read the failure logs.
-- Use `get_pipeline_job` to inspect the job's environment and timing.
-- Summarize the root cause and propose a fix based on the log output.
-
-## Example 3: Create and Manage an Issue
-
-Track a bug report discovered during development. Good agent behavior:
-
-- Use `create_issue` with project key, summary, description, and labels.
-- Use `create_issue_note` to add reproduction steps as a comment.
-- Use `update_issue` to set assignee and priority.
-- Use `create_branch` to start work from the issue branch naming convention.
-- Use `create_merge_request` when the fix is ready, linking the MR to the issue.

package/framework/skills/gitlab-mcp/references/code-review.md

@@ -1,110 +0,0 @@
-# Code Review Workflow
-
-## Overview
-
-Efficient code review uses a 2-step approach: list files first, then fetch diffs in batches.
-This avoids loading the entire diff payload at once.
-
-## Step 1: List Changed Files
-
-```
-list_merge_request_changed_files
-  project_id: "my-group/my-project"
-  mergeRequestIid: 42
-```
-
-Returns file paths with metadata:
-
-- `new_path`, `old_path` - file locations
-- `new_file`, `deleted_file`, `renamed_file` - change type flags
-
-Use `excluded_file_patterns` to skip generated files:
-
-```
-excluded_file_patterns: ["*.lock", "*.min.js", "dist/**"]
-```
-
-## Step 2: Batch Diff Retrieval
-
-```
-get_merge_request_file_diff
-  project_id: "my-group/my-project"
-  mergeRequestIid: 42
-  file_paths: ["src/api.ts", "src/utils.ts", "src/types.ts"]
-```
-
-**Batch 3-5 files per call** for optimal balance between API calls and response size.
-For large MRs (20+ files), prioritize reviewing:
-
-1. Source code files first (skip configs, lockfiles)
-2. New files before modified files
-3. Core logic before tests
-
-## Step 3: Leave Comments
-
-### Option A: Thread comments (visible immediately)
-
-```
-create_merge_request_thread
-  project_id: "my-group/my-project"
-  mergeRequestIid: 42
-  body: "Consider using a const here"
-  position:
-    new_path: "src/api.ts"
-    new_line: 15
-```
-
-Reply to existing threads:
-
-```
-create_merge_request_discussion_note
-  project_id: "my-group/my-project"
-  mergeRequestIid: 42
-  discussion_id: "abc123"
-  body: "Good point, updated"
-```
-
-### Option B: Draft notes (batch review)
-
-Create drafts, then publish all at once:
-
-```
-create_draft_note -> create_draft_note -> create_draft_note
-  ... repeat for each comment ...
-bulk_publish_draft_notes
-  project_id: "my-group/my-project"
-  mergeRequestIid: 42
-```
-
-This mimics GitHub's "pending review" pattern - all comments appear simultaneously.
-
-## Step 4: Resolve Threads
-
-```
-resolve_merge_request_thread
-  project_id: "my-group/my-project"
-  mergeRequestIid: 42
-  discussion_id: "abc123"
-  resolved: true
-```
-
-## Alternative: Full Diff Methods
-
-For small MRs where batching is unnecessary:
-
-- `get_merge_request_diffs` - all diffs at once (can be large)
-- `list_merge_request_diffs` - paginated diffs
-
-For comparing arbitrary refs:
-
-- `get_branch_diffs` - compare two branches or commits
-- `get_commit_diff` - single commit changes
-
-## Version Comparison
-
-Track review progress across force-pushes:
-
-```
-list_merge_request_versions  ->  get versions list
-get_merge_request_version    ->  get specific version details
-```