AIML-83: Improve README documentation structure #17
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
Restructured README to highlight the one-click VS Code install button: - Moved install button from status badge section to dedicated Quick Install section - Changed badge style to for-the-badge for better visibility - Positioned Quick Install after description, before security warnings - Added clear labeling and reference to other installation options Also updated CLAUDE.md with latest build commands and architecture details. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Converted the security warning section to use GitHub's callout syntax (> [!WARNING]) for better visual prominence and consistency with modern GitHub Markdown formatting. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Updated VS Code one-click install links to use input variable pattern
(${input:...}) instead of hardcoded example credentials. This follows
MCP security best practices by prompting users for credentials during
installation rather than exposing placeholder values.
Also refined the overview statement and improved warning formatting.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <[email protected]>
JacobMagesHaskinsContrast
approved these changes
Nov 7, 2025
Resolved conflicts in CLAUDE.md and README.md: - Kept improved documentation structure from AIML-83 branch - Integrated Testing section from main after Build section - Excluded Beads workflow documentation from public CLAUDE.md - Maintained detailed TOC with all subsections 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Move client-specific installation instructions to docs/installation-guides/ - Change terminology from "clients" to "MCP hosts" - Add both Docker and JAR deployment options to all guides - Create separate Download and Build from Source sections - Update API credentials link to personal-keys.html - Remove SNAPSHOT suffix from release JAR references - Add comprehensive installation guides index with deployment comparison - Keep VS Code installation prominent with one-click install Each installation guide now includes: - Prerequisites with deployment method choices - Docker deployment (recommended) - JAR deployment with download/build instructions - Verification steps and troubleshooting 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Show only Docker configurations on main README for primary users - IntelliJ and VS Code get complete Docker configs (copy-paste ready) - Remove duplicate VS Code install button from Installation section - Move Claude Desktop, Cline, oterm to "Other Hosts" with links only - Simplify Quick Start to actionable steps - Update Navigation table to reflect new structure - Reduce installation friction by showing configs directly - JAR deployment available via detailed guides Main README now shows 2 Docker configs instead of attempting to show all options. Serves IntelliJ (Java developers) and VS Code (web developers) as primary audiences. Other hosts and JAR deployment one click away. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
## README Changes - Consolidated Quick Start with Docker configs for IntelliJ & VS Code - Removed duplicate Installation section (configs now in Quick Start) - Removed Navigation table (document is concise enough) - Moved Data Privacy to end with advanced topics - Improved flow: Quick Start → Sample Prompts → Download → Advanced ## Installation Guide Updates - Added Claude Code installation guide with CLI-based setup - Added "(GitHub Copilot)" clarification to VS Code and IntelliJ guides - Clarified VS Code "Manual Installation" is Docker-based - Simplified "Related Documentation" to only link to main README and guides index - All guides now clearly separate Docker vs JAR deployment options ## Result Users can now get started faster with complete Quick Start configs and clear installation instructions across all supported MCP hosts. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add official Claude Code documentation reference link - Clarify placeholder replacement instructions across all guides - Improve formatting and readability of setup steps - Remove redundant alternative environment variable section from Claude Desktop guide - Standardize credential replacement messaging These changes make it easier for users to understand when and how to replace placeholder values with their actual Contrast credentials during setup. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Document proper bead title format with Jira issue ID prefix - Require external_ref parameter for Jira ticket linkage - Add reference to AGENTS.md from CLAUDE.md for workflow details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Consolidate Download and Build from Source into "Getting the JAR File" section with download as recommended option - Add introductory explanation for proxy configuration (corporate firewall use cases) - Simplify proxy examples to show only the changes needed instead of full configs - Fix VS Code proxy config to reference installation guide instead of showing inconsistent configuration - Make it clearer what needs to be added for proxy support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Clarify that MCP proxy config applies to ANY host (IntelliJ, VS Code, Claude Desktop, Cline, etc.), not just VS Code - Use IntelliJ mcp.json as complete example to show concrete implementation - Keep generic "what to add" instructions separate from host-specific example - Add note about VS Code's special input variable handling with link to guide This prevents confusion that proxy docs are VS Code-specific. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add #### headings to separate Direct Command vs MCP Configuration sections making it much easier to see document structure - Make Java proxy command multi-line for better readability - Show only the two properties/variables to add first, then complete examples - Add complete IntelliJ mcp.json example for JAR proxy configuration - Consistent "what to add" + "complete example" pattern throughout 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add "Choose ONE of the following" to both JAR and Docker proxy sections - Explain when to use Direct Command vs MCP Configuration File - Prevents confusion that users need to configure both options - Makes it clear: use Direct Command for CLI or MCP Config for MCP hosts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Reduce from 157 to 28 lines (82% reduction) - Convert to minimal navigation: Quick Links + Deployment comparison - Remove verbose feature lists - users know their tool, just need directions - Remove redundant requirements/help sections - details in individual guides - Users can now find their guide in ~3 seconds vs scrolling 150+ lines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Use parentheses notation for both VS Code (GitHub Copilot) and IntelliJ IDEA (GitHub Copilot) - Remove descriptions from Quick Links - just clean tool names - Eliminates mixing of "what it is" vs "how to install" descriptions - Cleaner, faster navigation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Rename "Quick Links" to "MCP Hosts" for clarity - Add note that server works with any MCP-compatible client - Guide users to adapt configs from documented hosts if theirs isn't listed - Makes it clear these are documented hosts, not the only supported ones 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add note block linking to VS Code's official MCP servers documentation - Consistent with Claude Code guide format and placement - Helps users access official documentation for additional context 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Change "contrastmcp" to "contrast" in all JSON configurations - Change "contrast-mcp" to "contrast" in VS Code install buttons - Consistent naming makes it simpler and cleaner for users - Affects README and all installation guides 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Button displays 'Install contrast-mcp' for clarity - Actual MCP server name remains 'contrast' in configuration - Balance between marketing visibility and technical simplicity 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Link from configuration scope step to detailed explanation below - Helps users understand the difference before choosing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add note block linking to Anthropic's MCP server connection documentation - Consistent with Claude Code and VS Code guide format 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Add note block linking to Cline's MCP server configuration documentation - Consistent with other guide formats 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Remove Next Steps sections from all installation guides - Remove Related Documentation sections from all guides - Keep only essential content focused on installation - Minor wording improvement to Claude Desktop note 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Fix typo: "loctaion" → "location" in certificate truststore path - Fix typo: "witin" → "within" in log location description - Fix typo: "sesssion" → "session" in sample prompts - Fix grammar: "you Contrast" → "your Contrast" in VS Code guide - Improve consistency and punctuation in sample prompts section - Clean up formatting in debug logging code example 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
ChrisEdwards
requested review from
JacobMagesHaskinsContrast and
jason-at-contrast
JacobMagesHaskinsContrast
approved these changes
Nov 12, 2025
Collaborator
JacobMagesHaskinsContrast
left a comment
JacobMagesHaskinsContrast
left a comment
There was a problem hiding this comment.
1 question about the beads directions in AGENTS.md. Otherwise this looks good.
Fix https statement
Fix https statement
Fix https statement
Fix https statement
Fix https statement
Fix https statement
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
This PR comprehensively overhauls the documentation to improve usability, consistency, and production-readiness. The main achievement is separating installation instructions into dedicated, platform-specific guides while streamlining the main README to focus on quick start and key features.
Key Improvements:
Changes by Category
📚 New Documentation Files
Installation Guides (
docs/installation-guides/)Each guide follows a consistent structure:
📝 README.md Refactoring
Structure Changes:
Improvements:
Visual Improvements:
> [!WARNING])🔄 Consistency & Standardization
MCP Server Name:
"contrast"across all configuration examples"contrastmcp"and"contrast-mcp"Configuration Examples:
example.contrastsecurity.com(host-agnostic)Documentation References:
Content Cleanup:
🔧 CLAUDE.md Enhancements
Updated Build Commands:
mvn clean package -DskipTestsmvn test -Dtest=HintGeneratorTestEnhanced Architecture Documentation:
Development Patterns:
Agent Guidelines (
AGENTS.md)Review Guide
🎯 Areas to Focus On
Installation Guides (
docs/installation-guides/)README.md Quick Start
Configuration Consistency
"contrast")Documentation References
🧪 Testing Checklist
📊 Impact Assessment
Lines Changed:
Files Modified: 10
User Experience Impact:
Migration Notes
No breaking changes. All existing configurations continue to work. Users with
"contrastmcp"as their server name can optionally update to"contrast"for consistency, but it's not required.🤖 Generated with Claude Code