{
  "markdown": "# Jira Service Management Assets MCP Server\n\nAn MCP (Model Context Protocol) server for interacting with the Jira Cloud Assets REST API (formerly Insight). Enables LLMs to query, retrieve, create, update, and delete assets, as well as search using natural language.\n\n## Prerequisites\n\n- Python >= 3.10\n- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`\n- Jira Cloud account with JSM Premium or Enterprise (Assets feature)\n- Jira API token ([create one here](https://id.atlassian.com/manage-profile/security/api-tokens))\n- **One** of the following for AI-powered natural language search:\n  - Anthropic API key (direct API access)\n  - Google Cloud project with Vertex AI enabled\n  - AWS account with Bedrock access\n  - Google AI Studio API key (Gemini)\n\n## Setup\n\n### 1. Clone and install\n\n```bash\ngit clone https://github.com/your-org/jsm-asset-mcp.git\ncd jsm-asset-mcp\nuv sync\n```\n\n### 2. Configure environment variables\n\nCreate a `.env` file in the project root:\n\n```env\nJIRA_DOMAIN=your-domain.atlassian.net\nJIRA_EMAIL=your-email@example.com\nJIRA_API_TOKEN=your_jira_api_token\n\n# Optional — auto-discovered if not set:\n# JIRA_CLOUD_ID=your_cloud_id\n# JIRA_WORKSPACE_ID=your_workspace_id\n```\n\n### 3. Configure LLM provider\n\nThe `search_assets` tool uses a structured-output LLM call to translate natural language into AQL queries. You can use Claude via the Claude Agent SDK (direct Anthropic API, Vertex AI, or Bedrock) or Gemini via Google AI Studio.\n\nSet `LLM_PROVIDER` to choose your provider:\n\n#### Option A: Anthropic API (default)\n\n```env\nLLM_PROVIDER=anthropic\nANTHROPIC_API_KEY=your_anthropic_api_key\n```\n\n#### Option B: Google Vertex AI\n\nAuthenticate with Google Cloud:\n```bash\ngcloud auth application-default login\n```\n\n```env\nLLM_PROVIDER=anthropic-vertex\nANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id\nANTHROPIC_VERTEX_REGION=global   # optional, defaults to global\n```\n\n#### Option C: Amazon Bedrock\n\nEnsure AWS credentials are configured (via `~/.aws/credentials`, env vars, or IAM role).\n\n```env\nLLM_PROVIDER=anthropic-bedrock\nAWS_REGION=us-east-1   # optional, defaults to us-east-1\n```\n\n#### Option D: Google AI Studio (Gemini)\n\nInstall the Gemini extra:\n```bash\nuv pip install '.[gemini]'\n# or: pip install '.[gemini]'\n```\n\nGet an AI Studio API key from https://aistudio.google.com/apikey — no GCP project needed.\n\n```env\nLLM_PROVIDER=gemini\nGEMINI_API_KEY=your_gemini_api_key\n```\n\n**Finding your Cloud ID:** Visit `https://your-domain.atlassian.net/_edge/tenant_info` in your browser — the `cloudId` field is what you need.\n\n**Finding your Workspace ID:** The server discovers this automatically, but you can also find it via the JSM Assets API: `GET https://your-domain.atlassian.net/rest/servicedeskapi/assets/workspace`\n\n## Configuring with Claude\n\n### Claude Desktop\n\nAdd this to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"jsm-assets\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/jsm-asset-mcp\", \"main.py\"],\n      \"env\": {\n        \"JIRA_DOMAIN\": \"your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your_jira_api_token\",\n        \"LLM_PROVIDER\": \"anthropic\",\n        \"ANTHROPIC_API_KEY\": \"your_anthropic_api_key\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code (CLI)\n\nAdd the MCP server to your project settings (`.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"jsm-assets\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/jsm-asset-mcp\", \"main.py\"],\n      \"env\": {\n        \"JIRA_DOMAIN\": \"your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your_jira_api_token\",\n        \"LLM_PROVIDER\": \"anthropic\",\n        \"ANTHROPIC_API_KEY\": \"your_anthropic_api_key\"\n      }\n    }\n  }\n}\n```\n\nOr add it via the CLI:\n\n```bash\nclaude mcp add jsm-assets -- uv run --directory /absolute/path/to/jsm-asset-mcp main.py\n```\n\nThen set the environment variables in your `.env` file or export them in your shell.\n\n### Gemini\n\nSee the included `gemini-extension.json` for Gemini-specific configuration.\n\n## Features / Available Tools\n\n### Core CRUD\n\n| Tool | Description |\n|------|-------------|\n| `execute_aql` | Run an AQL (Asset Query Language) query with pagination |\n| `get_object` | Get a single asset object by ID |\n| `get_object_attributes` | Get all attributes of a specific object |\n| `create_object` | Create a new asset object |\n| `update_object` | Update an existing asset object |\n| `delete_object` | Delete an asset object |\n\n### Schema Introspection\n\n| Tool | Description |\n|------|-------------|\n| `list_object_schemas` | List all object schemas in the workspace |\n| `get_object_schema` | Get details of a specific schema |\n| `list_object_types` | List all object types in a schema |\n| `get_object_type_attributes` | Get attribute definitions for an object type |\n| `get_schema_summary` | Human-readable summary of all schemas, types, and attributes |\n\n### Natural Language Search\n\n| Tool | Description |\n|------|-------------|\n| `search_assets` | Search assets using natural language — automatically translates to AQL |\n\n### Related Data\n\n| Tool | Description |\n|------|-------------|\n| `get_object_history` | Get the change history of an object |\n| `get_connected_tickets` | Get Jira tickets linked to an asset |\n\n## Natural Language Search\n\nThe `search_assets` tool lets you query assets without knowing AQL syntax. It uses the configured LLM to translate natural language into AQL:\n\n1. Inspects and caches the full schema (object types, attributes, and their data types)\n2. Sends the schema context and your question to the configured LLM for AQL generation\n3. Executes the generated AQL query\n4. Returns results along with the generated AQL for transparency\n\nFor natural-language searches, Claude returns a structured search plan with the AQL query, result type, and intended result limit. If the user asks for a count or total, `search_assets` uses `/object/aql/totalcount` for the exact count. If the user asks for all matching objects, it paginates through each `/object/aql` page until all matches are returned. If the user asks for a specific number, that number is used as the result limit. If no limit is specified, the tool's `max_results` parameter is used as the default.\n\nBecause the translation is AI-powered, it handles complex queries, synonyms, implied filters, and ambiguous phrasing far better than keyword matching. It understands your schema and can reason about which object types and attributes to query.\n\n**Examples:**\n\n```\n\"Find all laptops assigned to John\"\n\"Show me servers that haven't been updated in the last 6 months\"\n\"Which departments have the most software licenses?\"\n\"List network equipment in the Sydney office that's currently offline\"\n```\n\nThe generated AQL is included in the response (`_generated_aql` field) so you can verify and refine queries.\n\n## AQL Reference\n\nFor direct AQL queries via `execute_aql`, here are common patterns:\n\n```\nobjectType = \"Laptop\"                           # All objects of a type\nName = \"my-server-01\"                           # Exact match\nName LIKE \"server\"                              # Contains\nName STARTS WITH \"prod-\"                        # Prefix\nobjectType = \"Server\" AND Status = \"Active\"     # Multiple conditions\nobjectType = \"Server\" ORDER BY Name ASC         # Sorting\n```\n\n## API Base URL\n\nThis server uses the official Atlassian Assets REST API:\n\n```\nhttps://api.atlassian.com/ex/jira/{cloudId}/jsm/assets/workspace/{workspaceId}/v1\n```\n\nThe `cloudId` and `workspaceId` are auto-discovered from your `JIRA_DOMAIN` if not explicitly set.\n\n## Running Standalone\n\n```bash\nuv run main.py\n```\n\n## License\n\nMIT\n",
  "bytes": 7860,
  "sha": "b173c85f9762129805e8f503651e29613d659f15810f3fe8b61a63eaf70eebc6",
  "repo_slug": "ebarti/jsm-asset-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ebarti_jsm_asset_mcp_83de554a/readme"
}