{"id":30805555,"url":"https://github.com/aaronsb/atlassian-assets","last_synced_at":"2025-09-06T00:58:57.554Z","repository":{"id":305082545,"uuid":"1021611418","full_name":"aaronsb/atlassian-assets","owner":"aaronsb","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-18T04:52:18.000Z","size":5793,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-18T08:20:26.323Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-17T16:59:03.000Z","updated_at":"2025-07-18T04:52:21.000Z","dependencies_parsed_at":"2025-07-18T08:23:06.111Z","dependency_job_id":"7ab5cd3f-0d16-47bf-8cfa-e033487db476","html_url":"https://github.com/aaronsb/atlassian-assets","commit_stats":null,"previous_names":["aaronsb/atlassian-assets"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/atlassian-assets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fatlassian-assets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fatlassian-assets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fatlassian-assets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fatlassian-assets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/atlassian-assets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fatlassian-assets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842819,"owners_count":25177921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T00:58:52.922Z","updated_at":"2025-09-06T00:58:57.514Z","avatar_url":"https://github.com/aaronsb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Atlassian Assets CLI \u0026 MCP Server\n\nA dual-purpose tool for managing Atlassian Assets through both CLI and MCP (Model Context Protocol) interfaces, enabling both human operators and AI agents to manage assets programmatically.\n\n## 📖 Documentation\n\nComprehensive documentation is available in the **[/docs](./docs)** directory with organized sections for different user needs:\n\n- **[Use Cases](./docs/use-cases/)** - Real-world examples and scenarios \n- **[Integration Guides](./docs/guides/)** - Setup and configuration\n- **[Examples](./docs/examples/)** - Practical implementation patterns  \n- **[Architecture](./docs/architecture/)** - Technical deep-dives and system design\n- **[API Reference](./docs/api/)** - Complete tool and command documentation\n- **[Screenshots](./docs/screenshots/)** - Visual examples of Claude Desktop integration\n\n👉 **[Start with the documentation overview](./docs/README.md)** for guided navigation\n\n## Overview\n\nThis project provides CRUD operations for Atlassian Assets through two interfaces:\n1. **CLI Interface**: Direct command-line tool for human operators\n2. **MCP Server**: AI agent interface via Model Context Protocol\n\nBoth interfaces share the same underlying codebase, ensuring consistency and reducing maintenance overhead.\n\n## Features\n\n- **✅ Dual Interface**: CLI commands and MCP tools share common functionality\n- **✅ 13 MCP Tools**: Complete AI agent interface with intelligent guidance\n- **✅ 24+ CLI Commands**: Specialized commands for asset management and discovery\n- **✅ Complete CRUD Operations**: Create, read, update, and delete assets\n- **✅ Dual Search System**: Simple exact-match search and advanced AQL query search\n- **✅ Schema Management**: List schemas, get schema details, and explore object types\n- **✅ Pagination Support**: Handle large datasets with configurable limits\n- **✅ SDK Bug Fixes**: Direct HTTP implementation bypassing broken go-atlassian SDK methods\n- **✅ Contextual Hints**: Intelligent guidance system for streamlined workflows\n- **✅ AI-Specific Guidance**: Context-aware suggestions for AI agents\n- **✅ Version Management**: Proper semantic versioning with build-time injection\n- **✅ Multiple Output Formats**: JSON, YAML, and table output\n\n## Quick Start\n\n### 🚀 Build Both CLI and MCP Server\n\n```bash\n# Clone and build\ngit clone https://github.com/aaronsb/atlassian-assets\ncd atlassian-assets\n./build.sh\n\n# Or manual build\ngo build -o bin/assets ./cmd/assets          # CLI tool\ngo build -o mcp-server ./cmd/assets/mcp      # MCP server\n```\n\n### 🔧 Configuration\n\nCreate a `.env` file with your Atlassian credentials:\n\n```bash\nATLASSIAN_ASSETS_EMAIL=your.email@company.com\nATLASSIAN_ASSETS_HOST=yourcompany.atlassian.net\nATLASSIAN_ASSETS_API_TOKEN=your-api-token\nATLASSIAN_ASSETS_WORKSPACE_ID=your-workspace-id\n```\n\n## CLI Interface\n\n### Core CRUD Operations\n\n```bash\n# Create assets with intelligent workflow\n./bin/assets create --schema computers --type laptop --guided\n\n# List assets with pagination\n./bin/assets list --schema computers --limit 100 --offset 0\n\n# Get specific asset details  \n./bin/assets get --id OBJ-123\n\n# Update asset properties\n./bin/assets update --id OBJ-123 --data '{\"owner\":\"jane.doe\"}'\n\n# Delete assets (with safety controls)\n./bin/assets delete --id OBJ-123\n```\n\n### Advanced Search \u0026 Discovery\n\n```bash\n# Simple search with pagination\n./bin/assets search --simple \"MacBook Pro M3\" --schema 8\n./bin/assets search --simple \"*\" --schema 8 --limit 50 --offset 50\n\n# Advanced AQL search\n./bin/assets search --query \"Name = \\\"MacBook Pro\\\" AND Status = \\\"Active\\\"\"\n\n# Browse and explore  \n./bin/assets browse hierarchy --schema computers\n./bin/assets catalog --global-objects\n./bin/assets trace dependencies --object-type 65 --schema 8\n```\n\n### Schema \u0026 Metadata Management\n\n```bash\n# Schema operations\n./bin/assets schema list\n./bin/assets schema get --id computers  \n./bin/assets schema types --schema computers\n\n# Attribute management\n./bin/assets attributes --schema computers\n./bin/assets extract --schema computers --format csv\n```\n\n## MCP Server Interface\n\n### Available MCP Tools\n\nThe MCP server provides 13 tools with AI-specific guidance:\n\n| MCP Tool | Purpose | CLI Equivalent |\n|----------|---------|----------------|\n| `assets_list_schemas` | List all available schemas | `schema list` |\n| `assets_search` | Search for assets with dual modes | `search` |\n| `assets_list` | List objects with pagination | `list` |\n| `assets_get` | Get detailed object information | `get` |\n| `assets_create_object` | Create new asset instances | `create` |\n| `assets_delete` | Delete objects with validation | `delete` |\n| `assets_get_schema` | Get schema details | `schema get` |\n| `assets_create_object_type` | Create new object types | `schema create-type` |\n| `assets_get_object_type_attributes` | Get object type structure | `attributes` |\n| `assets_browse_schema` | Intelligent schema exploration | `browse hierarchy` |\n| `assets_validate` | Object validation against requirements | `validate` |\n| `assets_complete_object` | Intelligent object completion | `complete` |\n| `assets_trace_relationships` | Trace object dependencies | `trace dependencies` |\n\n### Claude Desktop Configuration\n\nAdd to your `~/.config/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"atlassian-assets\": {\n      \"command\": \"/path/to/mcp-server\",\n      \"args\": [],\n      \"env\": {\n        \"ATLASSIAN_ASSETS_EMAIL\": \"your.email@company.com\",\n        \"ATLASSIAN_ASSETS_HOST\": \"yourcompany.atlassian.net\",\n        \"ATLASSIAN_ASSETS_API_TOKEN\": \"your-api-token\",\n        \"ATLASSIAN_ASSETS_WORKSPACE_ID\": \"your-workspace-id\"\n      },\n      \"disabled\": false,\n      \"transportType\": \"stdio\",\n      \"autoApprove\": [\n        \"assets_list_schemas\",\n        \"assets_search\", \n        \"assets_get\",\n        \"assets_browse_schema\",\n        \"assets_get_schema\",\n        \"assets_get_object_type_attributes\"\n      ]\n    }\n  }\n}\n```\n\n### Claude Code Configuration\n\nAdd the MCP server to your Claude Code environment:\n\n```bash\n# Add server to Claude Code\nclaude mcp add atlassian-assets /path/to/mcp-server\n\n# List registered servers\nclaude mcp list\n\n# Remove server (if needed)\nclaude mcp remove atlassian-assets\n```\n\n### Other MCP Clients\n\nFor any JSON-based MCP client, use this configuration pattern:\n\n```json\n{\n  \"atlassian-assets\": {\n    \"command\": \"/path/to/mcp-server\",\n    \"env\": {\n      \"ATLASSIAN_ASSETS_EMAIL\": \"your.email@company.com\",\n      \"ATLASSIAN_ASSETS_HOST\": \"yourcompany.atlassian.net\", \n      \"ATLASSIAN_ASSETS_API_TOKEN\": \"your-api-token\",\n      \"ATLASSIAN_ASSETS_WORKSPACE_ID\": \"your-workspace-id\"\n    }\n  }\n}\n```\n\n## Architecture\n\n### Dual Interface Design\n\n```\n┌─────────────────┐    ┌─────────────────┐\n│   CLI Commands  │    │   MCP Tools     │\n│   (Human UI)    │    │   (AI Interface)│\n└─────────┬───────┘    └─────────┬───────┘\n          │                      │\n          └──────────┬───────────┘\n                     │\n         ┌───────────▼───────────┐\n         │   Common Package      │\n         │  ┌─────────────────┐  │\n         │  │   Foundation    │  │  # Core CRUD operations\n         │  │   (objects.go)  │  │\n         │  └─────────────────┘  │\n         │  ┌─────────────────┐  │\n         │  │   Composite     │  │  # Intelligent workflows\n         │  │   (browse.go)   │  │\n         │  └─────────────────┘  │\n         └───────────────────────┘\n                     │\n         ┌───────────▼───────────┐\n         │   Atlassian Assets    │\n         │      API Client       │\n         └───────────────────────┘\n```\n\n### Project Structure\n\n```\n├── cmd/assets/                  # CLI entry point\n│   ├── main.go                  # CLI commands\n│   ├── common/                  # Shared functionality\n│   │   ├── foundation/          # Core CRUD operations\n│   │   ├── composite/           # Intelligent workflows\n│   │   └── types.go             # Common interfaces\n│   └── mcp/                     # MCP server\n│       └── main.go              # MCP tool handlers\n├── internal/\n│   ├── client/                  # Atlassian API client\n│   ├── config/                  # Configuration management\n│   └── hints/                   # AI \u0026 CLI guidance systems\n├── reference/claude/            # Claude development guidelines\n└── .claude-github/              # GitHub integration files\n```\n\n## Development Status\n\n### ✅ Production Features (v1.0.0)\n\n- **Dual Interface**: CLI and MCP server with shared codebase\n- **Complete CRUD**: All asset management operations\n- **Advanced Search**: Dual search modes with full pagination\n- **Schema Management**: Full schema and object type operations\n- **AI Integration**: 13 MCP tools with context-aware guidance\n- **SDK Bug Fixes**: Direct HTTP implementation bypassing broken SDK methods\n- **Intelligent Workflows**: Contextual hints and guided operations\n- **Version Management**: Semantic versioning with build-time injection\n- **Authentication**: Environment variable and .env file support\n- **Live Testing**: Validated against real Atlassian Assets environment\n\n### 🚀 Future Enhancements\n\nSee our [GitHub Issues](https://github.com/aaronsb/atlassian-assets/issues) for planned improvements:\n\n- **Response Size Management**: Pagination and filtering recommendations (#6)\n- **Named Object Resolution**: Human-readable object references (#7)\n- **Enhanced Error Handling**: Structured error recovery (#8)\n- **Automated Testing**: Unit and integration test suites (#11)\n- **Logging \u0026 Monitoring**: Production-grade observability (#10)\n\n## Important Notes\n\n### SDK Issue and Fix\n\n**⚠️ Critical Bug Fixed**: The go-atlassian SDK v2.6.1 has a broken `Object.Filter()` method that makes AQL searches non-functional. This project includes a **direct HTTP implementation** that bypasses the broken SDK method.\n\n**Impact**: Without this fix, search and list operations would return empty results.\n\n**Solution**: See `./docs/architecture/sdk-fix-documentation.md` for complete technical details.\n\n**Upstream Issue**: https://github.com/ctreminiom/go-atlassian/issues/387\n\n### MCP vs CLI Differences\n\n| Feature | CLI Interface | MCP Interface |\n|---------|---------------|---------------|\n| **User Type** | Human operators | AI agents |\n| **Output** | Human-readable with next steps | Structured data with AI guidance |\n| **Error Handling** | User-friendly messages | Structured error responses |\n| **Workflow Hints** | CLI-specific suggestions | AI-specific context and recommendations |\n| **Response Size** | Full details | Optimized for context management |\n| **Authentication** | .env file or flags | Environment variables only |\n\n## Contributing\n\nThis project follows structured development with GitHub integration:\n\n1. **Requirements**: GitHub Issues with `requirement` label\n2. **Tasks**: GitHub Milestones for major features\n3. **Sub-tasks**: GitHub Issues with `task` label\n4. **Guidelines**: See `reference/claude/USER_SCOPE_CLAUDE.md`\n\n## License\n\nMIT License\n\n## Author\n\nAaron Bockelie","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fatlassian-assets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fatlassian-assets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fatlassian-assets/lists"}