{"id":43169556,"url":"https://github.com/jrmatherly/ai-workspace","last_synced_at":"2026-02-01T02:16:35.196Z","repository":{"id":333216994,"uuid":"1136580651","full_name":"jrmatherly/ai-workspace","owner":"jrmatherly","description":"AI/MCP Multi-Repo Workspace - Shared configuration and documentation","archived":false,"fork":false,"pushed_at":"2026-01-27T08:52:07.000Z","size":666,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T19:18:49.016Z","etag":null,"topics":["ai","claude-code","mcp","workspace"],"latest_commit_sha":null,"homepage":"https://github.com/jrmatherly/ai-workspace#readme","language":"Shell","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/jrmatherly.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":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-18T00:12:38.000Z","updated_at":"2026-01-20T05:32:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jrmatherly/ai-workspace","commit_stats":null,"previous_names":["jrmatherly/ai-workspace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jrmatherly/ai-workspace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrmatherly%2Fai-workspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrmatherly%2Fai-workspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrmatherly%2Fai-workspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrmatherly%2Fai-workspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jrmatherly","download_url":"https://codeload.github.com/jrmatherly/ai-workspace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jrmatherly%2Fai-workspace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28965050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T02:14:24.993Z","status":"ssl_error","status_checked_at":"2026-02-01T02:13:55.706Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","claude-code","mcp","workspace"],"created_at":"2026-02-01T02:16:34.588Z","updated_at":"2026-02-01T02:16:35.186Z","avatar_url":"https://github.com/jrmatherly.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI/MCP Multi-Repo Workspace\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.23--1.25-00ADD8?logo=go)](https://go.dev/)\n[![Projects](https://img.shields.io/badge/Projects-7-green.svg)](#-whats-inside)\n\n**A comprehensive collection of AI/MCP technologies, Kubernetes tools, and authentication systems.**\n\n\u003e 🚀 **Quick Start:** [Documentation Guide](./documentation/docs/reference/documentation-guide.md) • [Integration Guide](./documentation/docs/guides/cross-project-integration.md) • [Project Index](./documentation/docs/reference/project-index.md) • [API Reference](./documentation/docs/reference/api-reference.md)\n\n---\n\n## 📋 What's Inside\n\nThis workspace contains **7 independent projects** focused on cloud-native AI infrastructure:\n\n| Project | Description | Tech Stack |\n| --------- | ------------- | ------------ |\n| **[obot-entraid](./obot-entraid/)** 🔐 | MCP platform with custom auth (Entra ID, Keycloak) | Go, SvelteKit, PostgreSQL |\n| **[nah](./nah/)** ⚙️ | Kubernetes controller framework library | Go, controller-runtime |\n| **[kinm](./kinm/)** 🗄️ | K8s-like API server backed by PostgreSQL | Go, PostgreSQL |\n| **[mcp-oauth-proxy](./mcp-oauth-proxy/)** 🔑 | OAuth 2.1 proxy for MCP servers | Go, PostgreSQL/SQLite |\n| **[obot-tools](./obot-tools/)** 🛠️ | Tools, model providers, auth providers | Go, Python, TypeScript |\n| **[mcp-catalog](./mcp-catalog/)** 📚 | MCP server configuration catalog | YAML |\n| **[namegenerator](./namegenerator/)** 🎲 | Random name generator for containers/pods | Go (zero dependencies) |\n\n---\n\n## 🎯 Key Features\n\n### 🤖 AI/MCP Technologies\n\n- **MCP Server Hosting** - Deploy and manage Model Context Protocol servers\n- **Multi-Model Support** - OpenAI, Anthropic, Ollama, Groq, xAI, DeepSeek\n- **RAG Integration** - Knowledge base with vector search\n- **OAuth 2.1 Proxy** - Add authentication to any MCP server\n\n### ☸️ Kubernetes Tools\n\n- **Controller Framework** - Build custom controllers with declarative patterns\n- **API Server** - Create K8s-like CRUD APIs backed by PostgreSQL\n- **Leader Election** - High availability support\n\n### 🔐 Authentication\n\n- **Microsoft Entra ID** - Azure AD authentication with profile pictures\n- **Keycloak** - OpenID Connect authentication\n- **GitHub/Google OAuth** - OAuth2 providers\n- **Multi-Provider Proxy** - Unified OAuth 2.1 gateway\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n```bash\n# Check requirements\ngo version       # 1.23+ required\ngit --version\nmake --version\n\n# Optional (project-specific)\nnode --version   # 18+ for frontend\npython3 --version # 3.13+ for Python tools\ndocker --version\n```\n\n### Recommended: Use mise (Polyglot Tool Manager)\n\n[mise](https://mise.jdx.dev) manages all project tools and provides unified task running:\n\n```bash\n# Install mise\ncurl https://mise.run | sh\n\n# Install all tools (go, node, python, golangci-lint, gita)\ncd AI \u0026\u0026 mise trust \u0026\u0026 mise install\n\n# View available tasks\nmise tasks\n\n# Validate all projects\nmise all\n```\n\nSee [mise Configuration Guide](./.claude/instructions/mise-configuration-guide.md) for details.\n\n### Choose Your Path\n\n#### Path 1: Build a Kubernetes Controller\n\n```bash\ncd nah\nmake build \u0026\u0026 make test\n# See nah/README.md for examples\n```\n\n#### Path 2: Deploy MCP Platform\n\n```bash\ncd obot-entraid\nmake build\n# See obot-entraid/README.md for setup\n```\n\n#### Path 3: Add OAuth to MCP Server\n\n```bash\ncd mcp-oauth-proxy\nexport OAUTH_CLIENT_ID=\"...\" OAUTH_CLIENT_SECRET=\"...\"\nexport ENCRYPTION_KEY=\"$(openssl rand -base64 32)\"\ngo run .\n# See mcp-oauth-proxy/README.md for configuration\n```\n\n#### Path 4: Create Custom Tools\n\n```bash\ncd obot-tools\nmake build\n# See obot-tools/docs/DEVELOPER_GUIDE.md\n```\n\n---\n\n## 📚 Documentation\n\n### 📖 Essential Guides\n\n| Document | Purpose | Audience |\n| ---------- | --------- | ---------- |\n| **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** | One-page command reference | Active developers |\n| **[developer-onboarding.md](./documentation/docs/reference/developer-onboarding.md)** | Complete onboarding guide | New contributors |\n| **[cross-project-integration.md](./documentation/docs/guides/cross-project-integration.md)** | How projects integrate together | Architects, integrators |\n| **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** | Issue resolution guide | Debugging |\n| **[architecture.md](./documentation/docs/reference/architecture.md)** | Visual architecture diagrams | Architects, visual learners |\n| **[documentation-guide.md](./documentation/docs/reference/documentation-guide.md)** | Navigation and learning paths | Everyone |\n| **[project-index.md](./documentation/docs/reference/project-index.md)** | Comprehensive project reference | Developers, AI |\n| **[api-reference.md](./documentation/docs/reference/api-reference.md)** | Cross-project API documentation | API integrators |\n\n### 🎯 By Task\n\n- **Building Controllers?** → [nah/README.md](./nah/README.md)\n- **Adding OAuth?** → [mcp-oauth-proxy/README.md](./mcp-oauth-proxy/README.md)\n- **Deploying Obot?** → [obot-entraid/README.md](./obot-entraid/README.md)\n- **Creating Tools?** → [obot-tools/README.md](./obot-tools/README.md)\n- **Building APIs?** → [kinm/README.md](./kinm/README.md)\n- **MCP Integration?** → [mcp-catalog/PROJECT_INDEX.md](./mcp-catalog/PROJECT_INDEX.md)\n\n### 🤖 AI Assistant Guides\n\n**Expert Mode Onboarding** - For Claude Code AI assistants:\n\n```bash\n/expert-mode\n```\n\nThis intelligent onboarding command:\n\n- ✅ Auto-detects which project(s) you're working on (via directory, branch, keywords)\n- ✅ Loads relevant context efficiently (~20-30K tokens)\n- ✅ Provides comprehensive understanding of workspace structure\n- ✅ Enables immediate productivity with proper architectural context\n\nSee [Expert Mode Analysis](./EXPERT_MODE_ANALYSIS.md) for design details and token efficiency metrics.\n\n**Project-Specific CLAUDE.md Files:**\n\n- [obot-entraid/CLAUDE.md](./obot-entraid/CLAUDE.md) - MCP platform, auth providers, SvelteKit\n- [nah/CLAUDE.md](./nah/CLAUDE.md) - K8s controller framework patterns\n- [obot-tools/CLAUDE.md](./obot-tools/CLAUDE.md) - GPTScript tools, model/auth providers\n- [mcp-oauth-proxy/CLAUDE.md](./mcp-oauth-proxy/CLAUDE.md) - OAuth 2.1 flow, JWT handling\n- [mcp-catalog/CLAUDE.md](./mcp-catalog/CLAUDE.md) - MCP server catalog\n\n**Serena AI Memories** (`.serena/memories/`):\n\n- Project structure and purpose\n- Technology stack\n- Code style and conventions\n- Suggested commands\n- Task completion checklist\n- Architecture details\n\n---\n\n## 🏗️ Architecture\n\n### Workspace Structure\n\n```\nAI/\n├── obot-entraid/         # MCP platform (Go + SvelteKit)\n├── nah/                  # K8s controller framework (Go library)\n├── kinm/                 # K8s-like API server (Go + PostgreSQL)\n├── mcp-oauth-proxy/      # OAuth 2.1 proxy (Go)\n├── obot-tools/           # Tools \u0026 providers (Go/Python/TS)\n├── mcp-catalog/          # MCP configs (YAML)\n├── .claude/              # Claude Code config\n├── .serena/              # Serena AI memories\n├── documentation/\n│   ├── docs/             # Docusaurus source content\n│   │   ├── reference/    # Consolidated reference docs\n│   │   ├── guides/       # Implementation guides\n│   │   └── projects/     # Project work docs\n│   ├── archive/          # Superseded docs\n│   └── static/           # Static assets\n└── QUICK_REFERENCE.md    # Command reference\n```\n\n### Technology Stack\n\n- **Languages:** Go 1.23-1.25, Python 3.13+, TypeScript\n- **Frontend:** SvelteKit 5, Tailwind CSS 4\n- **Backend:** Kubernetes client-go, controller-runtime\n- **Databases:** PostgreSQL, SQLite\n- **AI/ML:** OpenAI, Anthropic, Ollama, local models\n- **Auth:** OAuth 2.0/2.1, OIDC, PKCE\n- **Observability:** OpenTelemetry, logrus\n- **Build:** mise, Make, Docker, Helm\n- **Multi-Repo:** gita (bulk git operations)\n\nSee [tech stack documentation](./.serena/memories/tech_stack_and_dependencies.md) for details.\n\n---\n\n## 🛠️ Development\n\n### Universal Commands\n\nWork across all Go projects:\n\n```bash\n# Build\nmake build\n\n# Test\nmake test\ngo test -race ./...      # With race detector\ngo test -cover ./...     # With coverage\n\n# Lint\nmake validate\ngolangci-lint run\n\n# Format\ngo fmt ./...\n\n# Dependencies\ngo mod tidy\n```\n\n### Pre-Commit Checklist\n\n```bash\ngo generate              # Generate code\ngo mod tidy              # Tidy dependencies\ngo fmt ./...             # Format\ngolangci-lint run        # Lint\ngo test ./...            # Test\nmake validate-ci         # CI validation (critical!)\n```\n\nSee [task completion checklist](./.serena/memories/task_completion_checklist.md) for details.\n\n---\n\n## 🎓 Learning Resources\n\n### Tutorials\n\n- **[nah Examples](./nah/docs/examples/)** - Kubernetes controller examples\n- **[obot-tools Guide](./obot-tools/docs/DEVELOPER_GUIDE.md)** - Tool development\n- **[Project Index](./documentation/docs/reference/project-index.md)** - Comprehensive reference\n\n### Architecture Docs\n\n- **[Codebase Architecture](./.serena/memories/codebase_architecture.md)** - Overall design\n- **[nah Architecture](./nah/docs/architecture/)** - Controller patterns\n- **[obot-tools Architecture](./obot-tools/docs/ARCHITECTURE.md)** - Tools design\n\n### Code Patterns\n\n- **[Code Style](./.serena/memories/code_style_and_conventions.md)** - Coding standards\n- **[Suggested Commands](./.serena/memories/suggested_commands.md)** - Common workflows\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Each project has specific guidelines:\n\n- **obot-entraid:** [CONTRIBUTING.md](./obot-entraid/CONTRIBUTING.md)\n- **nah:** [CONTRIBUTING.md](./nah/CONTRIBUTING.md)\n\n### General Guidelines\n\n1. **Follow Conventional Commits** - `feat(scope): description`\n2. **Run validation** - `make validate-ci` before committing\n3. **Add tests** - For new features\n4. **Update docs** - Keep documentation current\n5. **No secrets** - Never commit sensitive data\n\nSee [code style guide](./.serena/memories/code_style_and_conventions.md) for details.\n\n---\n\n## 📊 Project Statistics\n\n| Metric | Value |\n| -------- | ------- |\n| **Total Projects** | 6 independent modules |\n| **Languages** | Go, Python, TypeScript |\n| **Go Packages** | 140+ across all projects |\n| **Lines of Code** | ~50,000+ (estimated) |\n| **Documentation** | 40+ markdown files |\n\n---\n\n## 🔍 Common Use Cases\n\n### Use Case 1: Kubernetes Automation\n\n**Project:** nah  \n**Pattern:** Declarative controller with apply semantics  \n**Guide:** [nah/docs/guides/controllers.md](./nah/docs/guides/controllers.md)\n\n### Use Case 2: MCP Server Authentication\n\n**Project:** mcp-oauth-proxy  \n**Pattern:** OAuth 2.1 proxy with header injection  \n**Guide:** [mcp-oauth-proxy/README.md](./mcp-oauth-proxy/README.md)\n\n### Use Case 3: AI Model Integration\n\n**Project:** obot-tools  \n**Pattern:** OpenAI-compatible model providers  \n**Guide:** [obot-tools/docs/ARCHITECTURE.md](./obot-tools/docs/ARCHITECTURE.md)\n\n### Use Case 4: Custom API Servers\n\n**Project:** kinm  \n**Pattern:** PostgreSQL-backed K8s-like CRUD API  \n**Guide:** [kinm/docs/API.md](./kinm/docs/API.md)\n\n---\n\n## 🌟 Highlights\n\n### nah - Kubernetes Controller Framework\n\n- **94% token savings** with consolidated PROJECT_INDEX.md (15KB vs 300K+ full codebase)\n- **Declarative patterns** like `kubectl apply`\n- **Leader election** built-in for HA\n- **OpenTelemetry** integrated\n\n### obot-entraid - MCP Platform\n\n- **Custom auth providers** for Entra ID and Keycloak\n- **MCP hosting** for Node.js, Python, containers\n- **Chat client** with RAG and multi-model support\n- **Production fork** with active development\n\n### obot-tools - Provider Collection\n\n- **10+ model providers** (OpenAI, Anthropic, Ollama, etc.)\n- **Auth providers** for GitHub and Google\n- **Core tools** (memory, knowledge, tasks)\n- **Unified registry** via index.yaml\n\n### mcp-oauth-proxy - OAuth Gateway\n\n- **OAuth 2.1** with PKCE support\n- **Multi-provider** (Google, Microsoft, GitHub)\n- **Header injection** for user context\n- **Production-ready** with encryption\n\n---\n\n## 📄 License\n\nAll projects: **Apache License 2.0**\n\nSee individual LICENSE files in each project directory.\n\n---\n\n## 🔗 Links\n\n### Project Repositories\n\n- **obot-entraid:** Fork of [obot-platform/obot](https://github.com/obot-platform/obot)\n- **nah:** [github.com/obot-platform/nah](https://github.com/obot-platform/nah)\n- **obot-tools:** [github.com/jrmatherly/obot-tools](https://github.com/jrmatherly/obot-tools)\n\n### External Resources\n\n- **Obot Platform:** https://docs.obot.ai/\n- **MCP Specification:** https://modelcontextprotocol.io/\n- **Kubernetes:** https://kubernetes.io/docs/\n\n---\n\n## 📞 Support\n\n- **Documentation:** See [documentation-guide.md](./documentation/docs/reference/documentation-guide.md)\n- **Issues:** Open in respective project directories\n- **Questions:** Use GitHub Discussions\n\n---\n\n## 🎯 Next Steps\n\n### New Users\n\n1. Read [documentation-guide.md](./documentation/docs/reference/documentation-guide.md)\n2. Choose a project from [project-index.md](./documentation/docs/reference/project-index.md)\n3. Follow project README for setup\n4. Review examples and start coding\n\n### Contributors\n\n1. Review [Contributing Guidelines](#-contributing)\n2. Check [code style guide](./.serena/memories/code_style_and_conventions.md)\n3. Use [task checklist](./.serena/memories/task_completion_checklist.md)\n4. Submit PRs with Conventional Commits\n\n### AI Assistants\n\n1. Run `/expert-mode` command for intelligent onboarding\n2. Load project-specific context based on task\n3. Reference QUICK_REFERENCE.md for commands\n4. Use TROUBLESHOOTING.md when encountering issues\n\n---\n\n**Made with ❤️ for cloud-native AI infrastructure**\n\n*Last Updated: 2026-01-17*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrmatherly%2Fai-workspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjrmatherly%2Fai-workspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjrmatherly%2Fai-workspace/lists"}