@mohammadhprp/system-prompt 0.10.1

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

@@ -0,0 +1,116 @@
+# 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

@@ -0,0 +1,53 @@
+# 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-engineer`](../../skills/backend-engineer/SKILL.md): tracking feature work in Jira.
+- [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for debugging and testing.

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

@@ -0,0 +1,79 @@
+# 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

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

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

@@ -0,0 +1,13 @@
+{
+  "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

@@ -0,0 +1,94 @@
+# 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

@@ -0,0 +1,113 @@
+# 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/mcps/laravel-boost/README.md

@@ -0,0 +1,53 @@
+# Laravel Boost
+
+## Overview
+
+Laravel Boost is Laravel's first-party MCP server and AI-assistance package for Laravel applications. It gives AI coding agents project-aware Laravel context, local inspection tools, documentation search, generated AI guidelines, and optional agent skills.
+
+Official sources:
+
+- [Laravel Boost product page](https://laravel.com/ai/boost)
+- [Laravel Boost documentation](https://laravel.com/docs/boost)
+
+## Features
+
+- Exposes an MCP server from the Laravel application through `php artisan boost:mcp`.
+- Reads PHP, Laravel, database, package, and Eloquent model information.
+- Inspects routes, configuration, logs, browser errors, and database schema.
+- Executes database queries and Tinker code through MCP tools.
+- Searches Laravel's hosted documentation API with package-aware results.
+- Generates AI guidelines and skills for supported Laravel ecosystem packages.
+
+## Supported AI Clients
+
+Laravel Boost officially documents setup for Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot in VS Code, and Junie. The MCP server can also be registered manually in other MCP-compatible clients using the documented command and arguments.
+
+- OpenCode
+
+## When to Use
+
+Use Laravel Boost when an AI coding agent is working inside a Laravel application and needs current, project-specific Laravel context.
+
+Good fits:
+
+- Building or modifying Laravel features.
+- Inspecting routes, models, configuration, logs, or database schema.
+- Asking Laravel-version-specific implementation questions.
+- Upgrading or maintaining Laravel ecosystem packages supported by Boost guidelines or skills.
+
+Avoid using it as a generic MCP outside Laravel projects.
+
+## Requirements
+
+- A Laravel application.
+- PHP and Composer available in the project environment.
+- `laravel/boost` installed as a development dependency.
+- An AI client that supports MCP, or one of the clients Boost can configure during `php artisan boost:install`.
+- Local access to run `php artisan boost:mcp` from the Laravel application root.
+
+## Related Skills
+
+Relevant skills in this repository:
+
+- [`backend-engineer`](../../skills/backend-engineer/SKILL.md): feature work in Laravel applications.
+- [`backend-best-practices`](../../skills/backend-best-practices/SKILL.md): backend best practices for API design, database design, debugging, testing, and security.

package/framework/mcps/laravel-boost/capabilities.md

@@ -0,0 +1,92 @@
+# Laravel Boost Capabilities
+
+## What It Can Do
+
+### Application information
+
+Reads Laravel application details such as PHP version, Laravel version, database engine, installed ecosystem packages, package versions, and Eloquent models.
+
+### Database schema inspection
+
+Inspects database connections and schema so agents can reason about tables, columns, relationships, and constraints before changing code.
+
+### Database queries
+
+Executes database queries through the Laravel application environment. Use this carefully because the tool can access real project data when connected to a real database.
+
+### Route inspection
+
+Inspects application routes so agents can understand controllers, middleware, endpoints, and URL structure.
+
+### Artisan command discovery
+
+Lists and inspects available Artisan commands so agents can find framework and application commands without guessing.
+
+### Tinker execution
+
+Runs suggested PHP code through Laravel's runtime context. This is useful for focused inspection and debugging, but it should be treated as code execution with project permissions.
+
+### Configuration access
+
+Reads configuration keys and values to help agents generate code that matches the application environment.
+
+### Documentation search
+
+Queries Laravel's hosted documentation API using installed package context. This helps agents use current, version-aware Laravel ecosystem guidance.
+
+### Logs and browser errors
+
+Reads application logs, browser errors, and recent errors to support debugging workflows.
+
+### AI guidelines and skills
+
+Generates AI guidelines and optional agent skills for supported Laravel ecosystem packages detected in the project.
+
+## What It Cannot Do
+
+- It is not a generic MCP for non-Laravel projects.
+- It does not replace human review for database writes, migrations, authorization changes, or production-impacting commands.
+- It does not guarantee that every AI client supports every generated guideline or skill format.
+- It cannot safely infer production intent; agents still need explicit instructions before changing data or running destructive commands.
+- It cannot fix PHP, Composer, extension, container, or database connectivity issues outside the Laravel project environment.
+- It cannot make an unsupported AI client support MCP; unsupported clients require manual configuration or a compatible extension.
+
+## Best Practices
+
+- Install Boost as a development dependency only.
+- Run the MCP server from the Laravel application root.
+- Use a local or disposable database for agent-assisted exploration whenever possible.
+- Review database query and Tinker tool use before allowing write operations.
+- Keep generated Boost resources current with `php artisan boost:update`.
+- Prefer official Laravel documentation search through Boost when asking Laravel-version-specific questions.
+- Keep client-specific config examples separate even when the JSON schema is the same.
+- Avoid committing generated local agent configuration if it contains machine-specific paths or settings.
+
+## Common Workflows
+
+### Understand an existing Laravel application
+
+1. Ask the agent to inspect application info.
+2. Ask it to inspect routes and models relevant to the task.
+3. Ask it to inspect database schema before proposing code changes.
+4. Ask it to cite the files and Boost findings used in its plan.
+
+### Debug a failing request
+
+1. Reproduce the issue locally.
+2. Ask the agent to inspect recent logs and browser errors.
+3. Ask it to map the failing route to controller, middleware, model, and database dependencies.
+4. Apply the smallest fix and run regression tests.
+
+### Design a Laravel API change
+
+1. Use Boost to inspect routes, validation patterns, models, and schema.
+2. Apply this repository's `api-design`, `database-design`, and `testing` skills.
+3. Ask the agent to produce a compatibility and test plan before editing code.
+4. Verify with feature tests and targeted static checks.
+
+### Update Laravel ecosystem code
+
+1. Run `php artisan boost:update --discover` after dependency changes.
+2. Ask the agent to use Boost documentation search for version-specific guidance.
+3. Keep changes small and verify with the project's test suite.

package/framework/mcps/laravel-boost/configs/opencode.json

@@ -0,0 +1,9 @@
+{
+  "mcp": {
+    "laravel-boost": {
+      "type": "local",
+      "enabled": true,
+      "command": [ "php", "artisan",  "boost:mcp"]
+    }
+  }
+}