π GitHub Assistant β Telegram + Web Chat
A full-stack agentic chatbot that lets you manage your GitHub account through Telegram or a web chat interface. Powered by the OpenAI Agents SDK, a custom MCP (Model Context Protocol) server exposing 100+ GitHub API tools, and long-term memory via Mem0 + Qdrant.
β¨ Features
- π€ AI-Powered GitHub Agent β natural language β GitHub operations
- π¬ Telegram Bot β manage repos, issues, PRs, workflows straight from Telegram
- π Web Chat UI β Next.js dashboard with auth, chat, and profile management
- π§ Dual Memory β short-term (Redis, last 5 exchanges) + long-term (Mem0/Qdrant, semantic)
- π Per-User GitHub Tokens β each user connects their own PAT
- π³ Docker Compose β one-command deployment
ποΈ Architecture
ββββββββββββββββ ββββββββββββββββββββ ββββββββββββββββββββββββ
β Telegram ββββββββΆβ β β MCP GitHub Server β
β Bot API β β Web Service ββββββββΆβ (FastMCP, stdio) β
ββββββββββββββββ β (Next.js) β β 104 GitHub tools β
β β ββββββββββββββββββββββββ
ββββββββββββββββ β β’ Auth (NextAuthβ β²
β Web Chat ββββββββΆβ β’ /api/chat β β
β (Browser) β β β’ /api/telegram β ββββββββ΄βββββββ
ββββββββββββββββ β β’ Dashboard β β Agent Core β
ββββββββββ¬ββββββββββ β (OpenAI β
β β Agents SDK)β
ββββββββββββββββΌβββββββββββ ββββββββ¬βββββββ
βΌ βΌ βΌ β
ββββββββββ ββββββββββββ ββββββββββ ββββββ΄ββββββ
βMongoDB β β Redis β β Qdrant β β Mem0 β
β(Users) β β(History) β β(Vectors)β β(Memory) β
ββββββββββ ββββββββββββ ββββββββββ ββββββββββββ
| Service | Tech | Purpose |
|---|
| web_service | Next.js 16, NextAuth, Tailwind CSS | Auth, dashboard, web chat, Telegram webhook |
| mcp_server | FastAPI, OpenAI Agents SDK, FastMCP | AI agent + MCP GitHub tool server |
| MongoDB | Mongoose | User accounts (credentials, GitHub token, phone) |
| Redis | ioredis | Short-term conversation history (last 5 exchanges, 1h TTL) |
| Qdrant | Qdrant Cloud | Vector store for long-term semantic memory |
| Mem0 | mem0ai | Long-term memory layer over Qdrant |
π§ GitHub MCP Tools (104 total)
The MCP server exposes 104 tools covering nearly every GitHub API surface:
π Repositories (14 tools)
| # | Tool | Description |
|---|
| 1 | create_repository | Create a new repo (public/private, with README) |
| 2 | get_repository | Get full repo details (stars, forks, language, etc.) |
| 3 | list_repositories | List the authenticated user's repos |
| 48 | update_repository | Update settings (description, visibility, archive, etc.) |
| 47 | delete_repository | Delete a repo (requires delete_repo scope) |
| 34 | fork_repository | Fork a repo to your account or an org |
| 35 | list_forks | List forks of a repo |
| 49 | list_contributors | List contributors |
| 50 | get_repo_languages | Get language breakdown |
| 52 | list_repo_topics | List topics/tags |
| 53 | update_repo_topics | Replace all topics |
| 96 | get_readme | Get README content |
| 97 | list_directory_contents | Browse repo file tree |
| 100 | list_repo_invitations | List pending invitations |
πΏ Branches & Tags (8 tools)
| # | Tool | Description |
|---|
| 4 | create_branch | Create a branch from any source branch |
| 7 | list_branches | List all branches |
| 92 | delete_branch | Delete a branch |
| 6 | merge_branches | Merge one branch into another |
| 51 | list_tags | List tags |
| 93 | create_tag | Create lightweight or annotated tags |
| 94 | delete_tag | Delete a tag |
| 98 | compare_commits | Compare two branches/tags/SHAs |
π Files (4 tools)
| # | Tool | Description |
|---|
| 5 | push_file | Create or update a file on a branch |
| 45 | get_file_contents | Read file contents (auto-decodes base64) |
| 46 | delete_file | Delete a file with a commit |
| 97 | list_directory_contents | List directory contents |
π Pull Requests (7 tools)
| # | Tool | Description |
|---|
| 8 | create_pull_request | Open a new PR |
| 9 | list_pull_requests | List PRs (open/closed/all) |
| 10 | get_pull_request | Get PR details (mergeable, stats, etc.) |
| 11 | merge_pull_request | Merge a PR (merge/squash/rebase) |
| 12 | update_pull_request | Update title, body, or state |
| 13 | list_pull_request_files | List changed files in a PR |
| 14 | create_pull_request_review | Submit a review (approve/request changes/comment) |
π Issues (6 tools)
| # | Tool | Description |
|---|
| 15 | create_issue | Create an issue with labels & assignees |
| 16 | list_issues | List issues (filter by state, labels) |
| 17 | get_issue | Get full issue details |
| 18 | update_issue | Update title, body, state, labels, assignees |
| 19 | add_issue_comment | Comment on an issue or PR |
| 20 | list_issue_comments | List comments on an issue or PR |
π Search (4 tools)
| # | Tool | Description |
|---|
| 25 | search_repositories | Search repos by query, language, stars |
| 26 | search_code | Search code across repos |
| 27 | search_issues | Search issues and PRs |
| 28 | search_users | Search users by name, location, etc. |
π¦ Releases (3 tools)
| # | Tool | Description |
|---|
| 36 | create_release | Create a release (draft, prerelease supported) |
| 37 | list_releases | List releases |
| 38 | delete_release | Delete a release |
π·οΈ Labels & Milestones (5 tools)
| # | Tool | Description |
|---|
| 39 | create_label | Create a label with color |
| 40 | list_labels | List labels |
| 41 | delete_label | Delete a label |
| 85 | list_milestones | List milestones |
| 86 | create_milestone | Create a milestone with due date |
π₯ Collaborators (3 tools)
| # | Tool | Description |
|---|
| 42 | add_collaborator | Add a collaborator (pull/push/admin/maintain/triage) |
| 43 | remove_collaborator | Remove a collaborator |
| 44 | list_collaborators | List collaborators |
π Commits & Status (5 tools)
| # | Tool | Description |
|---|
| 21 | list_commits | List commits on a branch |
| 22 | get_commit | Get commit details (stats, changed files) |
| 23 | get_commit_status | Get combined CI/CD status for a ref |
| 24 | create_commit_status | Create a commit status (pending/success/failure) |
| 95 | list_check_runs | List check runs for a ref |
π Gists (4 tools)
| # | Tool | Description |
|---|
| 54 | create_gist | Create a public or secret gist |
| 55 | list_gists | List your gists |
| 56 | get_gist | Get a gist with file contents |
| 57 | delete_gist | Delete a gist |
β‘ GitHub Actions (5 tools)
| # | Tool | Description |
|---|
| 58 | list_workflows | List workflows in a repo |
| 59 | trigger_workflow | Trigger a workflow dispatch event |
| 60 | list_workflow_runs | List workflow runs (filter by status) |
| 61 | cancel_workflow_run | Cancel a running workflow |
| 62 | rerun_workflow | Re-run a workflow |
π’ Organizations & Teams (5 tools)
| # | Tool | Description |
|---|
| 63 | list_organizations | List your orgs |
| 64 | list_org_members | List org members |
| 65 | list_org_repos | List org repos |
| 66 | list_teams | List teams in an org |
| 67 | list_team_members | List team members |
π Webhooks (3 tools)
| # | Tool | Description |
|---|
| 68 | create_webhook | Create a repo webhook |
| 69 | list_webhooks | List webhooks |
| 70 | delete_webhook | Delete a webhook |
π€ User & Social (11 tools)
| # | Tool | Description |
|---|
| 29 | get_authenticated_user | Get your profile |
| 30 | get_user_profile | Get any user's public profile |
| 31 | star_repository | Star a repo |
| 32 | unstar_repository | Unstar a repo |
| 33 | list_starred_repositories | List your starred repos |
| 80 | follow_user | Follow a user |
| 81 | unfollow_user | Unfollow a user |
| 82 | list_followers | List followers |
| 83 | list_following | List who you follow |
| 84 | list_user_emails | List your email addresses |
| 99 | list_stargazers | List stargazers of a repo |
π Notifications (2 tools)
| # | Tool | Description |
|---|
| 71 | list_notifications | List notifications |
| 72 | mark_notifications_read | Mark all notifications as read |
π Keys (7 tools)
| # | Tool | Description |
|---|
| 73 | list_deploy_keys | List deploy keys |
| 74 | add_deploy_key | Add a deploy key |
| 75 | delete_deploy_key | Delete a deploy key |
| 76 | list_ssh_keys | List SSH keys |
| 77 | add_ssh_key | Add an SSH key |
| 78 | list_gpg_keys | List GPG keys |
| 79 | add_gpg_key | Add a GPG key |
π Deployments & Environments (3 tools)
| # | Tool | Description |
|---|
| 102 | list_deployments | List deployments |
| 103 | create_deployment_status | Create deployment status |
| 104 | list_environments | List deployment environments |
π¦ Packages, Codespaces, Projects & More (6 tools)
| # | Tool | Description |
|---|
| 87 | list_repo_projects | List classic projects |
| 88 | get_rate_limit | Check API rate limit |
| 89 | list_packages | List packages (npm, docker, etc.) |
| 90 | delete_package | Delete a package |
| 91 | list_codespaces | List codespaces |
| 101 | list_security_advisories | List security advisories |
π Quick Start
Prerequisites
- Node.js β₯ 20
- Python β₯ 3.12
- MongoDB (Atlas or local)
- Redis (local or cloud)
- Qdrant (cloud β qdrant.io)
- OpenAI API Key
- Telegram Bot Token (from @BotFather)
- GitHub Personal Access Token (per-user, added on dashboard)
1οΈβ£ Clone
git clone https://github.com/sandipto729/github_whatsapp.git
cd github_whatsapp
2οΈβ£ MCP Server Setup
cd mcp_server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
Create mcp_server/.env:
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_... # Default/fallback token
QDRANT_URL=https://xxx.qdrant.io
QDRANT_API_KEY=your_qdrant_key
Run:
uvicorn index:app --reload --port 8000
3οΈβ£ Web Service Setup
cd web_service
npm install
Create web_service/.env:
MONGODB_URI=mongodb+srv://...
REDIS_URL=redis://localhost:6379
NEXTAUTH_SECRET=some-random-secret
NEXTAUTH_URL=http://localhost:3000
MCP_SERVER_URL=http://localhost:8000
TELEGRAM_BOT_TOKEN=123456:ABC-...
NEXT_PUBLIC_APP_URL=http://localhost:3000
Run:
npm run dev
4οΈβ£ Set Telegram Webhook
GET http://localhost:3000/api/telegram/setup?url=https://your-public-url.com
π³ Docker Compose
# Create .env.docker files for both services (see above)
docker compose up --build -d
Services:
- web_service β
http://localhost:3040
- mcp_server β internal only (port 8000, not exposed)
π¬ Telegram Commands
| Command | Description |
|---|
/start | Welcome message + registration link |
/link <username> <password> | Link Telegram to your web account |
/me | Show your profile info |
/clear | Clear conversation history |
/help | List all commands |
| any text | Chat with the GitHub AI agent |
Example Conversations
You: Create a private repo called "my-api" with a README
Bot: β
Created private repo sandipto729/my-api with README
You: Create a branch "feature/auth" on my-api
Bot: β
Created branch feature/auth from main
You: Push a file src/main.py with a hello world script
Bot: β
Pushed src/main.py to feature/auth
You: Create a PR to merge feature/auth into main
Bot: β
Created PR #1 "Merge feature/auth into main"
You: List my open issues on my-api
Bot: No open issues found on sandipto729/my-api
You: Trigger the CI workflow on my-api
Bot: β
Triggered workflow ci.yml on branch main
π§ Memory System
| Layer | Storage | Scope | TTL |
|---|
| Short-term | Redis | Last 5 exchanges (10 messages) | 1 hour |
| Long-term | Mem0 β Qdrant | Semantic memories per user | Permanent |
The agent searches long-term memory before every response and saves each exchange after responding, giving it persistent context across sessions.
π Project Structure
github_whatsapp/
βββ docker-compose.yml
βββ README.md
β
βββ mcp_server/ # Python β AI Agent + MCP Server
β βββ Dockerfile
β βββ index.py # FastAPI entry point (/chat endpoint)
β βββ requirements.txt
β βββ chat/
β β βββ agent.py # OpenAI Agents SDK agent definition
β β βββ long_memory.py # Mem0 + Qdrant long-term memory
β βββ github_mcp/
β βββ mcp_github.py # FastMCP server β 104 GitHub tools
β
βββ web_service/ # Next.js β Web UI + Telegram Webhook
βββ Dockerfile
βββ package.json
βββ app/
β βββ page.js # Login / Register page
β βββ layout.js # Root layout
β βββ providers.js # NextAuth SessionProvider
β βββ globals.css # Tailwind styles
β βββ dashboard/
β β βββ page.js # User dashboard (token, phone, profile)
β βββ chat/
β β βββ page.js # Web chat interface
β βββ api/
β β βββ auth/
β β β βββ [...nextauth]/route.js # NextAuth handler
β β β βββ register/route.js # Registration endpoint
β β βββ chat/route.js # Web chat β MCP proxy
β β βββ telegram/route.js # Telegram webhook handler
β β βββ telegram/setup/route.js # Set Telegram webhook URL
β β βββ user/route.js # User profile CRUD
β βββ lib/
β βββ auth.js # NextAuth config (credentials)
β βββ db.js # MongoDB connection
β βββ memory.js # Redis short-term history
β βββ redis.js # Redis client
β βββ telegram.js # Telegram API helpers
β βββ models/
β βββ User.js # Mongoose User model
βββ public/
π GitHub Scopes Covered
The 104 tools map to these GitHub OAuth / PAT scopes:
| Scope | What It Enables |
|---|
repo | Full repo control β CRUD, branches, files, PRs, issues, collaborators |
repo:status | Read/create commit statuses, check runs |
repo_deployment | Deployments, deployment statuses, environments |
repo:invite | Repository invitations |
security_events | Security advisories |
workflow | GitHub Actions β list, trigger, cancel, re-run workflows |
write:packages / read:packages / delete:packages | Package management |
admin:org / read:org | Organizations, teams, members |
admin:repo_hook | Webhooks β create, list, delete |
admin:public_key | SSH keys, deploy keys |
admin:gpg_key | GPG keys |
gist | Create, list, read, delete gists |
notifications | List, mark-as-read notifications |
user / read:user | User profile |
user:email | Email addresses |
user:follow | Follow/unfollow users |
delete_repo | Delete repositories |
project / read:project | Classic projects |
codespace | List codespaces |
π License
MIT
π Credits