KorzunYuri/art-universe-mcp-server

Art Universe MCP Server

MCP server for deep analysis and understanding of the Art Universe project with comprehensive database access, Git integration, and knowledge management system.

Features

Analysis Tools:

1. load_project_context - Loads complete project context
2. analyze_modules - Analyzes module structure and dependencies
3. analyze_database - Analyzes database schema through Liquibase migrations
4. analyze_tests - Analyzes test coverage and archetypes
5. analyze_gradle - Analyzes Gradle configuration and dependencies
6. analyze_git - Analyzes Git history and current state
7. analyze_api - Analyzes REST API controllers and endpoints

Database Tools:

8. list_databases - Lists all available database connections
9. execute_sql - Executes SQL queries on specified database with automatic host resolution
10. list_tables - Lists tables in specified database schema
11. describe_table - Describes table structure in specified database
12. get_environment_info - Gets WSL detection and host resolution information

Git Tools:

13. git_status - Gets detailed git status with staged, unstaged, and untracked files
14. git_commit_history - Gets git commit history (oneline or detailed format)
15. git_add_files - Adds files to git staging area (works from WSL to Windows Git!)
16. git_diff - Shows git diff for files (working directory or staged changes)
17. git_commit_info - Gets detailed information about a specific commit

Knowledge Management System:

18. get_all_knowledge - Get all project knowledge (approved + AI discovered)
19. get_approved_knowledge - Get only approved project knowledge
20. get_ai_knowledge - Get only AI discovered knowledge
21. add_knowledge - Add new knowledge discovered by AI
22. update_knowledge - Update existing knowledge in AI knowledge base
23. remove_knowledge - Remove knowledge from AI knowledge base
24. search_knowledge - Search through all project knowledge
25. get_knowledge_stats - Get statistics about the knowledge base

Database Management

The server provides comprehensive PostgreSQL database access with automatic WSL ↔ Windows host resolution:

Database Configuration:

• Configuration stored in config/database-config.json
• Supports multiple database environments (dev, staging, prod)
• Automatic localhost → Windows host IP resolution in WSL environments

Database Connections:

• mu_raw_lastfm__dev - Development Database (Raw LastFM data)
• mu__dev - Development Database (approved data)
• mu_raw_lastfm__prod__old - Old Production Database
• mu_raw_lastfm__prod - New Production Database (Raw LastFM)
• mu__prod - New Production Database (approved data)

Usage Examples:

# List all databases
list_databases

# Execute SQL query with index statistics
execute_sql database="mu_raw_lastfm__prod" query="SELECT schemaname, tablename, indexname, idx_scan FROM pg_stat_user_indexes ORDER BY idx_scan DESC LIMIT 10"

# List tables in specific schema
list_tables database="mu_raw_lastfm__dev" schema="mu_raw_lastfm"

# Describe table structure
describe_table database="mu_raw_lastfm__dev" table="artist" schema="mu_raw_lastfm"

# Check environment info
get_environment_info

Git Integration

Full Git integration that works seamlessly from WSL to Windows repositories:

Git Features:

• Status tracking - Detailed status with staged/unstaged/untracked files
• Commit history - Browse commit history in multiple formats
• File management - Add files to staging area from AI
• Diff viewing - View changes in working directory or staged area
• Commit inspection - Get detailed information about specific commits

Usage Examples:

# Get detailed git status
git_status

# View recent commit history
git_commit_history limit=10 format="detailed"

# Add AI-created files to git
git_add_files files=["new-feature.js", "documentation.md"]

# View changes in specific files
git_diff files=["src/index.ts"] staged=false

# Get information about a commit
git_commit_info commit="HEAD~1"

Knowledge Management

The server includes a sophisticated knowledge management system:

Knowledge Files:

• knowledge/approved-knowledge.md - Developer-approved knowledge
• knowledge/ai-discovered-knowledge.md - AI-discovered insights

Usage Examples:

# Get all knowledge
get_all_knowledge

# Add new discovery
add_knowledge "New Pattern" "Discovered interesting architectural pattern..." "ai_discovery"

# Search knowledge base
search_knowledge "Spring Boot"

# Get knowledge statistics
get_knowledge_stats

See for detailed documentation.

Installation and Setup

1. Build Server

npm install
npm run build

2. Configure Database

Copy your database configuration to config/database-config.json:

{
  "databases": {
    "your_db_key": {
      "name": "Database Name",
      "host": "localhost",
      "port": 5432,
      "database": "database_name",
      "username": "username",
      "password": "password",
      "type": "local"
    }
  }
}

3. Add to Q CLI

The MCP server is configured in:

• ~/.config/q/mcp.json (global)
• .q/mcp.json (project local)

4. Restart Q CLI

After adding configuration, restart Q CLI:

q chat

WSL ↔ Windows Integration

The server automatically detects WSL environments and resolves Windows host connectivity:

Automatic Features:

• WSL Detection - Automatically detects if running in WSL
• Host Resolution - Converts localhost to Windows host IP in WSL
• Database Connectivity - Seamless connection to Windows PostgreSQL from WSL
• Git Integration - Full Git functionality from WSL to Windows repositories

Environment Detection:

# Check current environment
get_environment_info

Project Structure

art-universe-mcp-server/
├── src/                   # Source code
│   ├── analyzers/          # Analysis modules
│   │   ├── DatabaseConnector.ts
│   │   ├── GitAnalyzer.ts
│   │   └── ...
│   ├── utils/
│   │   └── HostResolver.ts # WSL/Windows host resolution
│   └── index.ts           # Main MCP server
├── config/
│   └── database-config.json # Database configuration
├── test/                  # Test files
├── dist/                  # Compiled files
└── README.md

Path Resolution

The MCP server uses dynamic path resolution:

• Server Configuration: Loaded from the server's own directory (config/database-config.json)
• Knowledge Files: Loaded from the working directory where the server is called (knowledge/)
• Project Analysis: Performed on the working directory (Git, modules, etc.)

This allows the server to be called from any project directory while maintaining its own configuration.

Usage Pattern:

# From your project directory (contains knowledge/)
cd /path/to/your/project

# Call the MCP server from anywhere
node /path/to/art-universe-mcp-server/dist/index.js

Testing

Run Tests:

# Test all database connections
node test/test-all-connections.js

# Test Git functionality
node test/test-git-functionality.js

# Test MCP tools
node test/test-mcp-tools.js

Test Results:

All tools have been tested and work correctly:

• ✅ Database Tools - Full PostgreSQL access with WSL support
• ✅ Git Tools - Complete Git integration from WSL to Windows
• ✅ Analysis Tools - Comprehensive project analysis
• ✅ Knowledge Management - AI knowledge accumulation system

Development

Development Commands:

# Development with auto-reload
npm run dev

# Build
npm run build

# Start
npm start

Adding New Tools:

1. Add tool definition in src/index.ts (ListToolsRequestSchema handler)
2. Add tool handler in src/index.ts (CallToolRequestSchema handler)
3. Implement functionality in appropriate analyzer
4. Add tests in test/ directory
5. Update README.md

Next Steps

1. Restart Q CLI to load the updated MCP server
2. Test database connectivity using list_databases and execute_sql
3. Try Git integration with git_status and git_commit_history
4. Use knowledge management for project understanding

The MCP server provides comprehensive project understanding with full database access, Git integration, and knowledge management capabilities, working seamlessly across WSL and Windows environments.