polaris

brandsoulmates/polaris

3.2

If you are the rightful owner of polaris and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Polaris is an MCP server that provides AI coding assistants with contextual knowledge about the Soulmates.ai codebase, architectural principles, and development standards.

Tools
4
Resources
0
Prompts
0

Polaris - Soulmates.ai MCP Server

Polaris is an MCP (Model Context Protocol) server that provides AI coding assistants with contextual knowledge about the Soulmates.ai codebase, architectural principles, and development standards.

What is This?

This project acts as a "corporate knowledge layer" for AI coding assistants like Claude Code and Cursor. It helps engineers by:

  • Preventing service sprawl (guidance on when to extend vs. create new services)
  • Providing up-to-date codebase documentation
  • Enforcing architectural standards (like spec-first development)
  • Accelerating onboarding for new engineers
  • Scaling architectural guidance across the team

Quick Start

Prerequisites

  • Python 3.14+
  • uv package manager
  • Claude Desktop or another MCP-compatible client

Installation

# Clone the repository
git clone https://github.com/brandsoulmates/polaris.git
cd polaris

# Install dependencies
uv sync

Configure with Claude Desktop

  1. Make the launch script executable:

    chmod +x run_mcp_server.sh

  2. Add to your Claude Desktop MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

    {
  "mcpServers": {
    "polaris": {
      "command": "/absolute/path/to/polaris/run_mcp_server.sh"
    }
  }
}

    Replace /absolute/path/to/polaris with the actual path where you cloned the repository.

  3. Restart Claude Desktop

That's it! Claude will now have access to Polaris tools and can help you understand the Soulmates.ai codebase architecture.

Verify It's Working

Open Claude Desktop and try asking:

  • "What services are available in the codebase?"
  • "Show me details about the orchestrator-tools-service"
  • "Where should I add a new sentiment analysis feature?"

For Maintainers: Updating the Knowledge Base

If you're maintaining Polaris and need to sync service documentation:

Setup Environment Variables

Create a .env file in the project root (copy from .env.example):

GITHUB_TOKEN=your_github_token_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

The script automatically loads .env - no need to export variables manually!

Generate Knowledge Base

The sync tool automatically:

  • Fetches documentation from service repositories (README, /docs, /specs)
  • Analyzes Python source code to extract:
    • Pydantic models (data contracts)
    • Database schemas (SQLAlchemy/MongoDB models)
    • Environment variables (required vs optional)
  • Generates LLM-optimized documentation with Claude
  • Fetches OpenAPI specs from live APIs
# Preview changes without modifying files
uv run python cli/sync_knowledge_base.py --dry-run

# Sync all services
uv run python cli/sync_knowledge_base.py --full

# Sync a specific service
uv run python cli/sync_knowledge_base.py --service soulmates-app-backend

What you'll see:

📦 Syncing soulmates-file-management...
  ✓ Found README.md
  ✓ Found 44 doc files in /docs
  ✓ Found 50 Python files
  ✓ Extracted 20 Pydantic models
  ✓ Extracted 76 environment variables
  ✓ Found live OpenAPI spec

🔒 Handling Protected APIs

If your APIs require authentication and can't be scraped directly, commit OpenAPI specs to your service repos:

# In each FastAPI service repo:
cp polaris/scripts/export_openapi_template.py scripts/export_openapi.py
python scripts/export_openapi.py  # Generates docs/openapi.json
git add docs/openapi.json && git commit -m "Add OpenAPI spec" && git push

Quick start: | All solutions:

Architecture

polaris/
├── registry.yaml              # Service catalog (manually maintained)
├── team-principles.md         # Architectural guidelines (manually maintained)
├── cli/
│   └── sync_knowledge_base.py # Documentation sync tool
├── scripts/                   # Helper scripts for service repos
│   ├── export_openapi_template.py
│   └── github_workflow_openapi_template.yml
├── knowledge-base/            # Auto-generated (don't edit directly)
│   ├── codebase-overview.md   # LLM-generated overview
│   └── services/
│       └── {service-name}/
│           ├── details.md     # LLM-optimized summary (primary)
│           ├── api-spec.json  # OpenAPI specification
│           └── raw/           # Full documentation for deep dives
│               ├── README.md
│               ├── docs/      # Recursive /docs from repo
│               └── specs/     # Recursive /specs from repo
└── server/
    └── main.py                # MCP server implementation

How It Works

  1. Service Registry (registry.yaml) - Lists all Soulmates.ai services
  2. Sync Tool - Fetches docs from GitHub, uses Claude AI to standardize them
  3. Knowledge Base - Auto-generated documentation in a consistent format
  4. MCP Server - Exposes knowledge to AI coding assistants via MCP protocol
  5. AI Assistant - Uses context to provide architectural guidance

MCP Resources & Tools

Resources (Automatically Available)

  • soulmates://codebase-overview - High-level architecture map
  • soulmates://team-principles - Decision-making frameworks

Tools (On-Demand)

  • list_services() - List all available services
  • get_service_details(service_name) - Detailed service documentation
  • get_api_spec(service_name) - OpenAPI specification
  • search_services(query) - Search services by capability

Usage Examples

Example 1: Deciding Where to Add a Feature

Engineer: "I want to build a new sentiment analysis tool"

Claude (with Polaris): "I see orchestrator-tools-service already contains
orchestrator tools. Let me check... [calls get_service_details]

Based on the team principles and existing architecture, I recommend
EXTENDING orchestrator-tools-service rather than creating a new service
because:
- It's logically related (both orchestrator tools)
- Service isn't overloaded (only 2 endpoints)
- Saves infrastructure setup time
- Keeps orchestrator tools in one place

However, I don't see a spec for this feature. Per team policy, let's
create /specs/sentiment-tool.md first."

Example 2: Understanding the Codebase

Engineer: "What services handle image processing?"

Claude (with Polaris): [calls search_services("image")]

"Found image-processing-service which handles:
- Image resizing and optimization
- Format conversion
- Watermarking
- ...

Use get_service_details('image-processing-service') for full documentation."

Maintaining the System

Adding a New Service

  1. Add entry to registry.yaml:

    - name: new-service
  repo: github.com/soulmates-ai/new-service
  type: tool-collection
  branch: main
  description: Brief description
  api_url: https://new-service-xxxxx.run.app  # Production API URL
  # Optional: openapi_url if OpenAPI spec is at custom location

  2. Run sync: uv run python cli/sync_knowledge_base.py

Note: The api_url is used to fetch the live OpenAPI spec from your deployed FastAPI service. The sync tool will try common endpoints like /openapi.json, /api/openapi.json, etc.

Updating Architectural Principles

  1. Edit team-principles.md directly
  2. Commit changes
  3. Principles are automatically available to AI assistants

Updating Service Documentation

  1. Update docs in the service repository (README.md, /docs folder)
  2. Run uv run python cli/sync_knowledge_base.py --service service-name
  3. Or wait for daily auto-sync (if GitHub Actions is set up)

Automation

The GitHub Actions workflow (.github/workflows/sync-knowledge-base.yml) automatically syncs the knowledge base:

  • Daily at 2 AM UTC - Full sync of all services
  • Manual trigger - Via GitHub UI (Actions tab)
  • Service-triggered - Services can trigger sync via repository_dispatch

Required GitHub Secrets

  • GITHUB_TOKEN - Automatically provided by GitHub Actions
  • ANTHROPIC_API_KEY - Add this to repository secrets

Development

Project Structure

cli/
  sync_knowledge_base.py    # Fetches docs, generates standardized content
server/
  main.py                   # MCP server with resources and tools

Running Tests

# Coming soon - tests not yet implemented
pytest

Contributing

  1. Follow the guidelines in CLAUDE.md
  2. Update team-principles.md if changing architectural decisions
  3. Test locally before committing
  4. Run sync tool to ensure knowledge base stays current

Troubleshooting

"registry.yaml not found"

Run commands from the project root directory.

"GITHUB_TOKEN not set"

export GITHUB_TOKEN="your_personal_access_token"

Get a token at: https://github.com/settings/tokens

"No services found in registry"

Add services to registry.yaml first.

"Could not access repository"

Ensure your GitHub token has access to the Soulmates.ai organization repositories.

Roadmap

Phase 1: MVP (Complete)

  • Service registry
  • Team principles document
  • CLI sync tool
  • MCP server with core tools
  • GitHub Actions automation

Phase 2: Enhancement (Planned)

  • Spec-first enforcement (check for specs in repos)
  • Template scaffolding tool
  • More sophisticated service search
  • Usage analytics and metrics

Phase 3: Intelligence (Future)

  • Semantic search with embeddings
  • Impact analysis ("what breaks if I change this?")
  • Pattern detection across services
  • Multi-product support (Social Index, Datarithm)

License

Internal use only - Soulmates.ai

Support

For questions or issues:

  • Check CLAUDE.md for detailed guidance
  • Review team-principles.md for architectural decisions
  • Contact the engineering team

Last Updated: 2025-01-15 Status: MVP Complete, Ready for Team Testing