# JSM Assets MCP Server - .dxt Installation
This document covers the new easy installation format using Anthropic's `.dxt` Desktop Extension format.
## What is .dxt?
The `.dxt` format is Anthropic's new packaging system for MCP servers that dramatically simplifies installation. Instead of manual configuration, you can now:
1. **Download** the `.dxt` file
2. **Double-click** to open with Claude Desktop
3. **Click "Install"** - that's it!
## Quick Installation
### Step 1: Download
Download `jsm-assets-mcp.dxt` from the releases or build it yourself:
```bash
npm run build:dxt
```
### Step 2: Install
1. Double-click `jsm-assets-mcp.dxt`
2. Claude Desktop will open the installation dialog
3. Click "Install"
4. Configure your credentials when prompted
### Step 3: Configure
During installation, you'll be prompted for:
- **JSM Workspace ID**: Your JSM Assets workspace identifier
- Example: `e15ec40f-3efb-44b0-a2a5-218bea7aa637`
- **Authentication Token**: Base64 encoded `email:api_token`
- Example: `Basic eW91ci1lbWFpbEBkb21haW4uY29tOkFUQVRUM3hGZkdGMDdyUDYuLi4...`
- **JSM Base URL** (optional): Defaults to `https://api.atlassian.com/jsm/assets/workspace`
- **Enable Debug Logging** (optional): Enable for troubleshooting
## Advantages of .dxt Format
### ✅ **One-Click Installation**
- No manual JSON configuration
- No dependency management
- No path configuration
### ✅ **User-Friendly Setup**
- GUI configuration forms
- Input validation
- Clear error messages
### ✅ **Self-Contained**
- All dependencies bundled
- No Node.js installation required
- Works across different systems
### ✅ **Automatic Updates**
- Claude Desktop can manage updates
- Version control built-in
- Rollback capabilities
## Comparison: Traditional vs .dxt Installation
### Traditional Method (Old Way)
```bash
# 1. Clone repository
git clone <repo-url>
cd jsm-assets-mcp
# 2. Install dependencies
npm install
# 3. Build project
npm run build
# 4. Manually edit Claude Desktop config
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
# 5. Add complex JSON configuration
{
"mcpServers": {
"jsm-assets": {
"command": "node",
"args": ["/full/path/to/jsm-assets-mcp/dist/index.js"],
"env": {
"JSM_WORKSPACE_ID": "your-workspace-id",
"JSM_AUTH_TOKEN": "Basic your-encoded-token",
"JSM_BASE_URL": "https://api.atlassian.com/jsm/assets/workspace"
}
}
}
}
# 6. Restart Claude Desktop
```
### .dxt Method (New Way)
```bash
# 1. Double-click jsm-assets-mcp.dxt
# 2. Click "Install"
# 3. Fill in the configuration form
# Done! 🎉
```
## Building Your Own .dxt File
If you want to customize or rebuild the .dxt package:
```bash
# Build the .dxt file
npm run build:dxt
# This runs:
# 1. Clean previous node_modules
# 2. Fresh npm install in dxt-package/server/
# 3. Bundle everything into jsm-assets-mcp.dxt
```
## .dxt Package Contents
The `.dxt` file contains:
```
jsm-assets-mcp.dxt (ZIP archive)
├── manifest.json # Extension metadata and configuration schema
├── icon.png # Extension icon (optional)
├── server/ # MCP server implementation
│ ├── index.js # Single-file server with all functionality
│ ├── package.json # Server dependencies
│ └── node_modules/ # Bundled dependencies (@modelcontextprotocol/sdk, axios)
└── dependencies/ # Reserved for additional dependencies
```
## Configuration Schema
The `.dxt` manifest defines user-configurable options:
```json
{
"configuration": {
"required": [
{
"name": "workspaceId",
"type": "string",
"title": "JSM Workspace ID",
"description": "Your JSM Assets workspace identifier"
},
{
"name": "authToken",
"type": "string",
"title": "Authentication Token",
"description": "Basic auth token (Base64 encoded email:token)",
"sensitive": true
}
],
"optional": [
{
"name": "baseUrl",
"type": "string",
"title": "JSM Base URL",
"default": "https://api.atlassian.com/jsm/assets/workspace"
},
{
"name": "enableDebug",
"type": "boolean",
"title": "Enable Debug Logging",
"default": false
}
]
}
}
```
## Troubleshooting .dxt Installation
### Installation Fails
- Ensure you have the latest Claude Desktop version
- Check that the `.dxt` file isn't corrupted (try re-downloading)
- Restart Claude Desktop and try again
### Configuration Errors
- Verify your JSM Workspace ID is correct
- Check that your auth token is properly Base64 encoded
- Ensure you have proper JSM Assets permissions
### Server Not Responding
- Enable debug logging in the configuration
- Check Claude Desktop's server logs
- Verify network connectivity to JSM APIs
### Getting Your JSM Credentials
1. **Workspace ID**: Found in your JSM Assets URL or admin settings
2. **Auth Token**: Create an API token in Atlassian and encode as:
```bash
echo -n "your-email@domain.com:your-api-token" | base64
```
Then prefix with `Basic ` → `Basic <base64-encoded-string>`
## Migration from Traditional Installation
If you previously installed using the traditional method:
1. **Remove old configuration** from `claude_desktop_config.json`
2. **Install the .dxt file** using the new method
3. **Configure credentials** in the GUI
4. **Test functionality** to ensure everything works
## Support
For issues with the .dxt installation:
- **General MCP Issues**: Check Claude Desktop documentation
- **JSM Assets Specific Issues**: Review the main README.md
- **Configuration Help**: Use the built-in validation and error messages
The .dxt format represents the future of MCP server distribution - making powerful integrations accessible to everyone! 🚀
