AI Integration: JSON Output, MCP Server, and Agent Resources #3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add comprehensive llms.txt file to make changie easily consumable by AI agents and LLMs. The file provides concise, structured documentation covering all core commands, workflows, and best practices optimized for Model Context Protocol (MCP) integration.
Fixed outdated table of contents entry that referenced the old command structure. The commands were restructured in v1.1.0 to use 'changie bump <type>' instead of 'changie <type>'.
Add machine-readable JSON output for CLI commands, making changie
agent-friendly and MCP-compatible.
- Added global --json flag to output structured results
- Created internal/output package for output formatting
- Updated version.Bump to return BumpResult struct
- Updated cmd/bump to support JSON output mode
- Added app.json_output to config registry
JSON output provides structured data including success status, versions,
files modified, and error messages, enabling AI agents and tools to easily
parse command results.
Example:
changie bump minor --json
# Output: {"success":true,"old_version":"1.0.0","new_version":"1.1.0",...}
Significantly improved help text for major, minor, and patch bump commands to be more LLM and agent-friendly: - Added clear "WHAT IT DOES" section with step-by-step workflow - Added "EXAMPLES" section with practical use cases - Added "COMMON USE CASES" section to guide when to use each command - Improved Short descriptions to be more informative - Added JSON output example to each command This makes it much easier for AI agents to understand when and how to use each version bump type, supporting the overall goal of MCP integration.
Created examples/ directory with practical usage scripts demonstrating changie in various real-world scenarios: - basic-workflow.sh: Simple day-to-day usage patterns - ci-integration.sh: CI/CD pipeline integrations (GitHub Actions, GitLab) - release-workflow.sh: Various release strategies and workflows - README.md: Complete guide to all examples with best practices These examples serve multiple purposes: 1. Help new users learn changie quickly 2. Provide copy-paste templates for CI/CD setup 3. Enable AI agents to understand common usage patterns 4. Document best practices and troubleshooting All examples include JSON output usage, making them particularly valuable for MCP integration and agent-driven workflows.
Created .ai/ directory following emerging 2025 patterns for AI-augmented development, providing structured resources for AI agents and LLMs: - context.md: Complete project context, capabilities, constraints, and best practices for AI agents - prompts/release-new-version.md: Step-by-step release guide - prompts/add-changelog-entry.md: Changelog entry categorization guide - workflows/complete-release-workflow.md: End-to-end release workflow - README.md: Directory documentation and MCP integration guidance This structure enables: 1. AI agents to quickly understand changie 2. MCP servers to expose changie as tools 3. Automation tools to integrate reliably 4. Consistent agent behavior across platforms All prompts and workflows emphasize JSON output usage and error handling, making changie fully agent-ready for MCP and other AI integrations.
Added full test coverage for internal/output package: - Tests for IsJSONEnabled(), WriteJSON(), WriteString(), Write() - Tests for all output structs (BumpOutput, InitOutput, etc.) - JSON indentation verification - Coverage increased from 0% to 83.3% Also updated .golangci.yml to exclude thelper warnings for table-driven test check functions, which are not actual test helpers. Overall test coverage: 82.2%
Implements Model Context Protocol (MCP) server using official Go SDK v1.0.0 to expose changie operations as tools for AI agents like Claude. **What's Added:** - MCP server binary (cmd/mcp-server/main.go) - Tool handlers (internal/mcp/tools.go) for: - changie_bump_version: Bump semantic versions - changie_add_changelog: Add changelog entries - changie_init: Initialize changie projects - changie_get_version: Get current version from git - Comprehensive test suite (internal/mcp/tools_test.go) - Dockerfile.mcp for containerized deployment - Task command: `task build:mcp` - Updated .ai/README.md with MCP server documentation **Architecture:** - Built with official MCP Go SDK (github.com/modelcontextprotocol/go-sdk) - Uses stdio transport (JSON-RPC 2.0) - Leverages existing --json flag from changie commands - Returns structured output for reliable agent parsing **Usage:** Build: `task build:mcp` Run: `./changie-mcp-server` Docker: `docker build -f Dockerfile.mcp -t changie-mcp .` Integrates with Claude Desktop and other MCP-compatible AI tools.
Adds convenient Task commands for Docker workflows: - task docker:build:mcp - Build Docker image with version tags - task docker:run:mcp - Run MCP server container - task docker:test:mcp - Test Docker image - task docker:clean:mcp - Clean up Docker artifacts Updated .ai/README.md to document new Task commands. Follows project pattern of using Task for all automation.
The go.mod requires Go 1.24.0 but Dockerfile was using golang:1.23-alpine, causing build failures. Updated to golang:1.24-alpine for compatibility. Docker image builds successfully and is only 52.1MB.
- Add comprehensive integration guide for Claude Desktop, Cursor, and Claude Code - Document JSON output, MCP server, and AI agent resources in README - Update CLAUDE.md with new packages (internal/output, internal/mcp) - Simplify CHANGELOG entries to be user-focused - Add analysis files to .gitignore - Fix formatting in MCP tests
|
You have run out of free Bugbot PR reviews for this billing cycle. This will reset on November 26. To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial. |
Codecov Report❌ Patch coverage is @@ Coverage Diff @@
## main #3 +/- ##
==========================================
+ Coverage 78.99% 79.46% +0.47%
==========================================
Files 30 32 +2
Lines 1152 1271 +119
==========================================
+ Hits 910 1010 +100
- Misses 194 208 +14
- Partials 48 53 +5
🚀 New features to boost your workflow:
|
Move JSON output formatting logic from cmd/bump.go into internal/version/bump.go to follow architecture principle of keeping business logic out of cmd layer. Changes: - internal/version/bump.go now handles both text and JSON output - Simplified cmd/bump.go to thin wrapper (removed 25 lines) - Changed Bump() signature: (*BumpResult, error) → error - Updated all tests to match new signature - JSON output still works identically for end users Adheres to architecture principle: cmd layer should only map config and delegate to internal packages.
- Add .codecov.yml to exclude cmd/mcp-server/ from coverage - Add JSON unmarshaling tests for all MCP output types - Add tests for invalid JSON handling - Improves test count from 410 to 418 tests
- Add setupIntegrationTestRepo helper to create real git repos - Add integration tests for BumpVersion (major, minor, patch) - Add integration tests for AddChangelog, Init, GetVersion - Build changie binary in TestMain for integration testing - Coverage improvements: - internal/mcp: 63.9% → 86.1% (+22.2pp) - BumpVersion: 63.6% → 90.9% - AddChangelog: 50.0% → 75.0% - Init: 63.6% → 90.9% - Total test count: 418 → 425 (+7 tests)
The AddChangelog integration tests create a CHANGELOG.md in the internal/mcp/ directory as a side effect. Ignore this test artifact.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Transforms changie into an AI-ready tool with comprehensive integration for AI assistants and automation workflows.
Key Features:
--jsonflag) for CI/CD pipelinesChanges
JSON Output Support
--jsonflag to all bump commandsinternal/outputpackage with output structuresMCP Server
changie_bump_version,changie_add_changelog,changie_init,changie_get_versionDocumentation & Resources
.ai/directory with agent context, prompts, and workflowsllms.txtfor LLM-optimized documentationexamples/with CI/CD workflow scriptsImpact
For Users:
For AI Agents:
Test Plan
New Packages:
internal/output- JSON output utilitiesinternal/mcp- MCP server toolscmd/mcp-server- MCP server entry pointNew Directories:
.ai/- AI agent resourcesexamples/- Usage examples