{"id":31158072,"url":"https://github.com/ntanwir10/codesage-algolia-challenge","last_synced_at":"2026-04-11T03:10:38.783Z","repository":{"id":306089838,"uuid":"1023881922","full_name":"ntanwir10/codesage-algolia-challenge","owner":"ntanwir10","description":"An intelligent, conversational code discovery platform built around Algolia MCP Server that revolutionizes how developers explore and understand codebases through natural language conversations.","archived":false,"fork":false,"pushed_at":"2025-07-23T14:35:27.000Z","size":168,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-23T16:29:23.239Z","etag":null,"topics":["algolia-search","fastapi","mcp-server","python3","rate-limiting","react","real-time-processing","sqlite","typescript","websockets"],"latest_commit_sha":null,"homepage":"","language":"Python","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/ntanwir10.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-21T21:04:13.000Z","updated_at":"2025-07-23T15:21:33.000Z","dependencies_parsed_at":"2025-07-23T16:29:25.935Z","dependency_job_id":"4cb91165-ddd7-4048-88b1-68c526979d1a","html_url":"https://github.com/ntanwir10/codesage-algolia-challenge","commit_stats":null,"previous_names":["ntanwir10/codesage-algolia-challenge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ntanwir10/codesage-algolia-challenge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fcodesage-algolia-challenge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fcodesage-algolia-challenge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fcodesage-algolia-challenge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fcodesage-algolia-challenge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ntanwir10","download_url":"https://codeload.github.com/ntanwir10/codesage-algolia-challenge/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ntanwir10%2Fcodesage-algolia-challenge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275852036,"owners_count":25540136,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["algolia-search","fastapi","mcp-server","python3","rate-limiting","react","real-time-processing","sqlite","typescript","websockets"],"created_at":"2025-09-18T23:30:22.764Z","updated_at":"2025-09-18T23:30:25.891Z","avatar_url":"https://github.com/ntanwir10.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CodeSage - MCP-First Code Discovery\n\n🚀 **AI-powered code discovery through natural language** - Built entirely around the **Model Context Protocol (MCP)** for seamless integration with Claude Desktop and other AI clients.\n\n\u003e **CodeSage - MCP-First Code Discovery** - The only code discovery tool built entirely around the Model Context Protocol for seamless AI integration.\n\n**Built for the [Algolia MCP Server Challenge](https://dev.to/challenges/algolia-2025-07-09)** 🏆\n\n\u003e Competing in the **Backend Data Optimization** and **Ultimate User Experience** categories with our innovative MCP-first approach to code discovery.\n\n## 🎯 What is CodeSage?\n\n**CodeSage - MCP-First Code Discovery** transforms GitHub repositories into **AI-searchable knowledge bases** through the Model Context Protocol. Submit a repository URL, and within minutes your AI assistant can discover functions, understand architecture, and answer complex questions about the codebase through natural language - all via MCP integration.\n\n### **🎯 Final User Experience**\n\n```text\n1. User submits: github.com/facebook/react\n2. System processes: GitHub → Parser → Algolia\n3. User opens Claude Desktop  \n4. User asks: \"Show me React's rendering lifecycle\"\n5. Claude uses MCP tools to search and analyze\n6. User gets AI-powered code insights\n```\n\n## 📊 Data Flow Architecture\n\n```arch_flow\n┌─────────────┐    ┌──────────────┐    ┌─────────────┐\n│   Frontend  │───▶│   Backend    │───▶│   Algolia   │\n│   (Simple)  │    │ (Processing) │    │  (Search)   │\n└─────────────┘    └──────────────┘    └─────────────┘\n                            │\n                            ▼\n                   ┌──────────────┐    ┌─────────────┐\n                   │     MCP      │───▶│   Claude    │\n                   │   Protocol   │    │  Desktop    │\n                   └──────────────┘    └─────────────┘\n```\n\n### **Key Flows:**\n\n- **Repository Management**: Frontend ↔ Backend\n- **Code Discovery**: Claude Desktop ↔ MCP ↔ Backend ↔ Algolia\n- **No Direct Integration**: Frontend never talks to Algolia or MCP\n\n## ✨ Core Features\n\n### 🔧 **MCP-First Architecture** - Our Unique Differentiator\n\n- Built entirely around **Model Context Protocol** - the only code discovery tool with this architecture\n- Works with **Claude Desktop** and any MCP-compatible AI client\n- **No direct AI API calls** - all intelligence through MCP integration\n- **Seamless AI Integration** - designed specifically for MCP-based AI workflows\n\n### 🔍 **GitHub Repository Processing**\n\n- **Automatic ingestion** from GitHub repository URLs\n- **Code parsing** for functions, classes, imports across multiple languages\n- **Algolia indexing** for fast, semantic code search\n\n### 🤖 **Natural Language Code Discovery**\n\n- Ask questions like *\"How does authentication work?\"*\n- AI models search and analyze through MCP tools\n- **Contextual, conversational** code exploration\n\n### 🎯 **Simple Repository Management**\n\n- Submit repository URLs for processing\n- Track processing status (pending → processing → completed)\n- Manage repository lifecycle (create, list, delete)\n\n## 🚀 Quick Start\n\n### Setup Prerequisites\n\n- Python 3.9+ with virtual environment\n- Node.js 18+ and npm\n- Algolia account (App ID + Admin API Key)\n\n### 1. **Development Mode (Recommended)**\n\n```bash\n# Setup environment\nmake setup\n# Edit .env with your Algolia credentials\n\n# Start backend + frontend together\nmake start\n\n# Or start individually:\nmake start-backend    # Backend on :8001\nmake start-frontend   # Frontend on :5173\n```\n\n### **Manual Development Setup**\n\nIf you prefer to run servers manually without Make commands:\n\n#### **Backend Server:**\n\n```bash\n# Navigate to project root\ncd /Users/ntanwir/Developer/codesage-algolia-challenge\n\n# Activate virtual environment\nsource .venv/bin/activate\n\n# Go to backend directory  \ncd backend\n\n# Start FastAPI server\npython -m uvicorn app.main:app --reload --port 8001\n```\n\n#### **Frontend Server** (in separate terminal)\n\n```bash\n# Navigate to project root\ncd /Users/ntanwir/Developer/codesage-algolia-challenge\n\n# Go to frontend directory\ncd frontend\n\n# Install dependencies (first time only)\nnpm install\n\n# Start React development server\nnpm run dev\n```\n\n#### **What to Expect:**\n\n**Backend Server (Terminal 1):**\n\n```text\nINFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)\nINFO:     Started reloader process [xxxxx] using WatchFiles\nINFO:     Started server process [xxxxx]\nINFO:     Waiting for application startup.\nINFO:     Application startup complete.\n```\n\n✅ **Backend ready:** `http://localhost:8001`\n\n- API Docs: `http://localhost:8001/docs`\n- Health Check: `http://localhost:8001/health`\n\n**Frontend Server (Terminal 2):**\n\n```text\n  Local:   http://localhost:5173/\n  Network: use --host to expose\n  press h + enter to show help\n```\n\n✅ **Frontend ready:** `http://localhost:5173`\n\n#### **Quick Test:**\n\n```bash\n# Test backend health (in Terminal 3)\ncurl http://localhost:8001/health\n\n# Test MCP endpoints\ncurl http://localhost:8001/api/v1/ai/mcp\n```\n\n### 2. **Docker Mode**\n\n```bash\n# For container-based development\nmake build\nmake up               # Both services via Docker\n\n# Check status\nmake health\nmake logs\n```\n\n### 3. **Which approach to use?**\n\n**✅ Use Development Mode when:**\n\n- Actively developing/debugging code\n- Need fast reload/hot-swapping\n- Working on frontend styling\n- Debugging MCP integration\n\n**✅ Use Docker Mode when:**\n\n- Testing production-like environment\n- Demonstrating to others\n- CI/CD pipeline\n- Consistent environment across team\n\n### **Environment Configuration**\n\nCreate `.env` file with your Algolia credentials:\n\n```bash\nALGOLIA_APP_ID=your_app_id\nALGOLIA_ADMIN_API_KEY=your_admin_key\nSECRET_KEY=your-secret-key-here\n```\n\n### **Testing MCP Endpoints**\n\nOnce your backend is running on `:8001`, test these endpoints:\n\n```bash\n# 1. MCP Server Information (NEW!)\ncurl http://localhost:8001/api/v1/ai/mcp\n\n# 2. MCP Capabilities  \ncurl http://localhost:8001/api/v1/ai/mcp/capabilities\n\n# 3. Available MCP Tools\ncurl http://localhost:8001/api/v1/ai/mcp/tools\n\n# 4. Tool Call Instructions (if you try GET - shows how to use POST)\ncurl http://localhost:8001/api/v1/ai/mcp/tools/call\n\n# 5. MCP Resources (with required uri parameter)\ncurl \"http://localhost:8001/api/v1/ai/mcp/resources/read?uri=codesage://repositories\"\n\n# 6. Resources without uri (shows usage instructions)\ncurl http://localhost:8001/api/v1/ai/mcp/resources/read\n\n# 7. Execute Tool (POST request - the correct way)\ncurl -X POST http://localhost:8001/api/v1/ai/mcp/tools/call \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"tool_name\": \"search_code\", \"arguments\": {\"query\": \"function\"}}'\n```\n\n**💡 Common Errors Fixed:**\n\n- ❌ `GET /mcp/tools/call` → ✅ Now shows usage instructions\n- ❌ `GET /mcp/resources/read` (no uri) → ✅ Now shows required parameters\n- ✅ All endpoints now provide helpful error messages\n\n**💡 Tip:** Visit `http://localhost:8001/docs` for interactive API documentation!\n\n### Usage with Claude Desktop\n\n1. **Submit repository**: POST to `/api/v1/repositories/` with GitHub URL\n2. **Wait for processing**: Repository status becomes \"completed\"\n3. **Connect Claude Desktop**: Configure MCP connection to `http://localhost:8001`\n4. **Ask questions**: Use natural language to explore the codebase\n\n## 🛠 API Endpoints\n\n### Repository Management\n\n```API\nGET    /api/v1/repositories/        # List repositories\nPOST   /api/v1/repositories/        # Create repository  \nGET    /api/v1/repositories/{id}    # Get repository\nDELETE /api/v1/repositories/{id}    # Delete repository\n```\n\n### MCP Protocol\n\n```API\nGET    /api/v1/ai/mcp/capabilities     # MCP server capabilities\nGET    /api/v1/ai/mcp/tools           # List MCP tools\nPOST   /api/v1/ai/mcp/tools/call      # Execute MCP tool\nGET    /api/v1/ai/mcp/resources/read  # Read MCP resource\n```\n\n## 📦 MCP Tools Available\n\n- **`search_code`** - Natural language code search across repositories\n- **`analyze_repository`** - Repository overview and architectural insights\n- **`explore_functions`** - Function discovery and relationship mapping\n- **`explain_code`** - Detailed code explanations and documentation\n- **`find_patterns`** - Pattern detection for security, performance, architecture\n\n## 🔧 Technical Stack\n\n### Backend\n\n- **FastAPI** - Modern Python web framework\n- **SQLAlchemy** - Database ORM with PostgreSQL/SQLite\n- **Algolia** - Search and indexing engine\n- **Pydantic** - Data validation and settings\n\n### Frontend (Optional)\n\n- **React 18** - Modern UI framework\n- **TypeScript** - Type safety\n- **TailwindCSS** - Utility-first styling\n- **Vite** - Fast development and building\n\n### MCP Integration - Our Core Innovation\n\n- **Model Context Protocol** - AI integration standard (our primary differentiator)\n- **Claude Desktop** - Primary AI client with seamless MCP integration\n- **Tool-based architecture** - Extensible AI capabilities through MCP tools\n- **MCP-First Design** - Every feature built around MCP protocol standards\n\n## 📚 Documentation\n\n- [`docs/architecture.md`](docs/architecture.md) - Technical architecture and implementation details\n- [`.env.example`](.env.example) - Environment configuration template\n\n## 📁 Project Structure\n\n```tree\ncodesage-algolia-challenge/\n├── backend/                    # FastAPI MCP Server\n│   ├── app/\n│   │   ├── api/v1/endpoints/  # API endpoints (repositories, ai, performance)\n│   │   ├── core/              # Configuration and database\n│   │   ├── models/            # SQLAlchemy models\n│   │   ├── schemas/           # Pydantic schemas\n│   │   ├── services/          # Business logic services\n│   │   └── main.py           # FastAPI application\n│   ├── requirements.txt       # Python dependencies\n│   └── Dockerfile            # Container configuration\n├── frontend/                  # React TypeScript UI\n│   ├── src/\n│   │   ├── components/       # Reusable UI components\n│   │   ├── pages/           # Application pages\n│   │   ├── services/        # API client and WebSocket\n│   │   └── types/           # TypeScript definitions\n│   └── package.json         # Node.js dependencies\n├── deployment/              # Infrastructure \u0026 deployment\n│   ├── docker-compose.yml   # Development setup\n│   ├── docker-compose.prod.yml # Production setup\n│   ├── nginx.conf          # Reverse proxy config\n│   └── DOCKER.md           # Docker documentation\n├── tests/                   # Organized test suites\n│   ├── api/                # API endpoint tests\n│   ├── mcp/                # MCP protocol tests\n│   └── postman/            # Postman collection\n├── docs/                   # Technical documentation\n└── README.md              # Project overview\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntanwir10%2Fcodesage-algolia-challenge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fntanwir10%2Fcodesage-algolia-challenge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fntanwir10%2Fcodesage-algolia-challenge/lists"}