Nbkristagent
A powerful AI-powered Telegram bot built with TypeScript, LangChain, and Google Gemini, featuring tool integration and MCP (Model Context Protocol) support.
Installation
npx nbkristagentAsk AI about Nbkristagent
Powered by Claude Β· Grounded in docs
I know everything about Nbkristagent. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
NbkristAgent π€
A powerful AI-powered Telegram bot built with TypeScript, LangChain, and Google Gemini, featuring tool integration and MCP (Model Context Protocol) support.
π Features
- Conversational AI: Powered by Google Gemini 2.0 Flash for natural, engaging conversations
- Tool Integration: Built-in tools for attendance tracking and calculations
- MCP Support: Extensible architecture with Model Context Protocol for connecting to external tools
- Chat History: Maintains context with the last 5 message exchanges
- Telegram Integration: Seamless bot experience on Telegram with markdown formatting
- Error Handling: Robust error handling and graceful degradation
π οΈ Built-in Tools
Attendance Tools
- Overall Attendance: Get attendance percentage for students
- Detailed Attendance: Retrieve comprehensive attendance information including subject-wise breakdown
MCP Tools
The bot can be extended with external MCP servers:
- PDF Generator: Generate PDFs from markdown content
- SearXNG Search: Web search capabilities with privacy-focused SearXNG
π Prerequisites
- Node.js (ES2022+ support)
- pnpm package manager
- Telegram Bot Token (from @BotFather)
- Google AI API Key (for Gemini model)
π§ Installation
-
Clone the repository
git clone https://github.com/tobioffice/NbkristAgent.git cd NbkristAgent -
Install dependencies
pnpm install -
Environment Setup Create a
.envfile in the root directory:TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here GOOGLE_API_KEY=your_google_ai_api_key_here -
Configure MCP Servers (Optional) Update the MCP server paths in
src/tools/mcpTools/mcpClient.ts:const MCP_SERVERS: McpServerConfig[] = [ { name: "pdf-generator", command: "node", args: ["/path/to/your/pdf-generator-mcp-server/dist/index.js"], }, { name: "searxng", command: "node", args: ["/path/to/your/searxng-mcp-server/dist/index.js"], env: { SEARXNG_URL: "http://your-searxng-instance-url", }, }, ];
π Usage
-
Start the bot
pnpm start -
Interact on Telegram
- Find your bot on Telegram
- Send messages and the AI will respond
- Use tools by mentioning relevant keywords (e.g., "attendance for roll number 123")
ποΈ Architecture
Core Components
src/agent.ts: Main AI agent with LangChain integration, tool binding, and conversation managementsrc/bot.ts: Telegram bot implementation with message handling and markdown sanitizationsrc/tools/tools.ts: Built-in tools for attendance and calculationssrc/tools/mcpTools/: MCP integration for external tool connectivity
Key Features
- Chat Memory: Maintains last 10 messages (5 exchanges) for context
- Tool Execution: Automatic tool calling with loading indicators
- Response Formatting: Telegram-compatible markdown with proper sanitization
- Multi-language Support: Can respond in other languages while keeping script in English
π§ Development
Project Structure
NbkristAgent/
βββ src/
β βββ agent.ts # Main AI agent logic
β βββ bot.ts # Telegram bot implementation
β βββ tools/
β βββ tools.ts # Built-in tools
β βββ mcpTools/ # MCP integration
β βββ mcpClient.ts
β βββ wrapper.ts
βββ package.json
βββ tsconfig.json
βββ README.md
Adding New Tools
-
Built-in Tools: Add to
src/tools/tools.tsexport const yourTool = new DynamicStructuredTool({ name: "your_tool_name", description: "Description of your tool", schema: z.object({ param: z.string().describe("Parameter description"), }), func: async (input) => { // Your tool logic here return "Tool result"; }, }); -
MCP Tools: Configure in
src/tools/mcpTools/mcpClient.ts
Scripts
pnpm test: Run tests (currently placeholder)pnpm start: Start the bot (add this to package.json scripts)
π¦ Dependencies
Core Dependencies
- @langchain/core: LangChain core functionality
- @langchain/google-genai: Google Gemini integration
- @langchain/mcp-adapters: MCP adapter for LangChain
- @modelcontextprotocol/sdk: MCP SDK
- telegraf: Telegram bot framework
- zod: Schema validation
Development Dependencies
- @types/node: Node.js type definitions
π€ Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request
π License
ISC License
π Acknowledgments
- Built with LangChain
- Powered by Google Gemini
- Telegram integration via Telegraf
- MCP support through Model Context Protocol
Note: This bot is designed for educational and demonstration purposes. Ensure compliance with Telegram's terms of service and API usage guidelines.
