├── README.md ├── instruction_mcp_server.md └── init_telegram_openai_agent.md /README.md: -------------------------------------------------------------------------------- 1 | # Awesome One Hit Vibe Code 2 | 3 | 🚀 Build powerful applications/modules with just one prompt using LLM agent tools like Cursor, Windsuft, GitHub Copilot, etc. This is the future of developer productivity. 4 | 5 | ## 💡 Concept 6 | 7 | One Hit Vibe Coding is a modern approach to software development where you generate a full project (including architecture, file structure, and code) with a single, carefully crafted instruction. 8 | 9 | With the rise of AI coding agents and frameworks like Cursor Agent Mode, developers can build meaningful, scalable services faster than ever. 10 | 11 | This repo highlights the power of this approach using the MCPHub ecosystem. 12 | 13 | ## 🧱 How It Works 14 | 15 | 1. Use the instruction_mcp_server.md prompt. 16 | 2. Run it on an LLM-based agentic IDE (e.g. Cursor). 17 | 3. One hit = fully working MCP Server for a cloud tool. 18 | 19 | ## 📦 One Prompt Instruction 20 | 21 | - Use this universal instruction to generate your own MCP server: 22 | 👉 [instruction_mcp_server.md](instruction_mcp_server.md) 23 | - Create a Telegram bot with OpenAI integration 24 | 👉 [init_telegram_openai_agent.md](init_telegram_openai_agent.md) 25 | 26 | ## 🧪 Example Projects Built in One Hit 27 | 28 | Here are five real-world MCP Servers for Azure services, each created by running the single prompt: 29 | 30 | | Service | Repo | 31 | |---------|------| 32 | | Azure Storage Blob | [gaia-vault-mcp](https://github.com/Cognitive-Stack/gaia-vault-mcp) | 33 | | Azure DevOps Git | [ares-devops-mcp](https://github.com/Cognitive-Stack/ares-devops-mcp) | 34 | | Azure Document Intelligence | [orion-vision-mcp](https://github.com/Cognitive-Stack/orion-vision-mcp) | 35 | | Azure Cosmos DB | [atlas-datahub-mcp](https://github.com/Cognitive-Stack/atlas-datahub-mcp) | 36 | | Azure Cognitive Search | [hermes-search-mcp](https://github.com/Cognitive-Stack/hermes-search-mcp) | 37 | | AI Chatbot Telegram | [bull-vision-agent](https://github.com/Cognitive-Stack/bull-vision-agent) | 38 | 39 | ## 🎯 Why This Matters 40 | 41 | - No setup fatigue 42 | - No repetitive boilerplate 43 | - Focus on design and flow, not on wiring up basic components 44 | 45 | ## 🧩 Tools You Can Use 46 | 47 | - Cursor – Agent Mode with prompt-first development 48 | - GitHub Copilot / Copilot Workspace 49 | - Windsuft Agent SDK (coming soon) 50 | 51 | ## 🌱 Contribute 52 | 53 | Want to showcase your own One Hit Vibe project? 54 | 55 | 1. Fork this repo 56 | 2. Add your project link and description 57 | 3. PR it in! 58 | 59 | --- 60 | 61 | Made with ❤️ by Cognitive Stack · Empowering builders in the AI era 62 | -------------------------------------------------------------------------------- /instruction_mcp_server.md: -------------------------------------------------------------------------------- 1 | # Instructions for Creating a New MCP Server 2 | 3 | ## Project Structure 4 | 5 | ``` 6 | src/ 7 | ├── config/ # Configuration management 8 | ├── services/ # Tool registration 9 | ├── tools/ # Tool implementations 10 | ├── types/ # TypeScript types 11 | └── index.ts # Server entry 12 | ``` 13 | 14 | 15 | ## 1. Initial Setup 16 | 17 | ### Create Project 18 | ```bash 19 | mkdir your-mcp-server 20 | cd your-mcp-server 21 | npm init -y 22 | ``` 23 | 24 | ### Install Dependencies 25 | 26 | ```bash 27 | # Core dependencies 28 | npm install fastmcp zod dotenv 29 | # Add your domain-specific dependencies here 30 | 31 | # Dev dependencies 32 | npm install -D typescript tsx @types/node jest ts-jest @types/jest 33 | ``` 34 | 35 | ## 2. Configuration Files 36 | 37 | ### package.json 38 | ```json 39 | { 40 | "name": "your-mcp-server", 41 | "version": "1.0.0", 42 | "description": "Your MCP Server Description", 43 | "main": "dist/index.js", 44 | "types": "dist/index.d.ts", 45 | "bin": { 46 | "your-mcp-server": "dist/index.js" 47 | }, 48 | "files": [ 49 | "dist", 50 | "README.md", 51 | "LICENSE" 52 | ], 53 | "scripts": { 54 | "dev": "tsx src/index.ts", 55 | "build": "tsc", 56 | "start": "node dist/index.js", 57 | "test": "jest", 58 | "test:watch": "jest --watch", 59 | "test:coverage": "jest --coverage", 60 | "prepare": "npm run build" 61 | } 62 | } 63 | ``` 64 | 65 | ### jest.config.js 66 | ```javascript 67 | module.exports = { 68 | preset: "ts-jest", 69 | testEnvironment: "node", 70 | moduleFileExtensions: ["ts", "js"], 71 | transform: { 72 | "^.+\\.ts$": "ts-jest", 73 | }, 74 | testMatch: ["**/__tests__/**/*.test.ts"], 75 | moduleNameMapper: { 76 | "^@/(.*)$": "/src/$1", 77 | }, 78 | }; 79 | ``` 80 | 81 | ### tsconfig.json 82 | ```json 83 | { 84 | "compilerOptions": { 85 | "target": "ES2020", 86 | "module": "CommonJS", 87 | "lib": ["ES2020"], 88 | "declaration": true, 89 | "outDir": "./dist", 90 | "rootDir": "./src", 91 | "strict": true, 92 | "esModuleInterop": true, 93 | "skipLibCheck": true, 94 | "forceConsistentCasingInFileNames": true, 95 | "moduleResolution": "node", 96 | "resolveJsonModule": true, 97 | "isolatedModules": true 98 | }, 99 | "include": ["src/**/*"], 100 | "exclude": ["node_modules", "dist", "**/*.test.ts"] 101 | } 102 | ``` 103 | 104 | ## 3. Implementation Guide 105 | 106 | ### Types (src/types/tools.ts) 107 | ```typescript 108 | import { z } from "zod"; 109 | import { FastMCP } from "fastmcp"; 110 | 111 | export type ToolConfig = { 112 | name: string; 113 | description: string; 114 | parameters: z.ZodObject; 115 | execute: (args: any) => Promise; 116 | }; 117 | 118 | export type Tool = FastMCP["addTool"]; 119 | ``` 120 | 121 | ### Configuration (src/config/env.ts) 122 | ```typescript 123 | export const getConfig = () => { 124 | const requiredVar = process.env.REQUIRED_VARIABLE; 125 | if (!requiredVar) { 126 | throw new Error("REQUIRED_VARIABLE environment variable is not set"); 127 | } 128 | return { requiredVar }; 129 | }; 130 | ``` 131 | 132 | ### Tool Implementation (src/tools/example-tool.ts) 133 | ```typescript 134 | import { getConfig } from "../config/env"; 135 | 136 | export default async ( 137 | param1: string, 138 | param2: string, 139 | options: { option1?: string; option2?: boolean } 140 | ) => { 141 | const config = getConfig(); 142 | 143 | // Validate inputs 144 | if (!options.option1 && !options.option2) { 145 | throw new Error("Either option1 or option2 must be provided"); 146 | } 147 | 148 | // Implement tool logic 149 | try { 150 | // Your implementation here 151 | return "Operation successful"; 152 | } catch (error) { 153 | throw new Error(`Operation failed: ${error.message}`); 154 | } 155 | }; 156 | ``` 157 | 158 | ### Tool Registration (src/services/tools.ts) 159 | ```typescript 160 | import { z } from "zod"; 161 | import exampleTool from "../tools/example-tool"; 162 | import { ToolConfig } from "../types/tools"; 163 | 164 | export const tools: ToolConfig[] = [ 165 | { 166 | name: "example-tool", 167 | description: "Description of what the tool does", 168 | parameters: z.object({ 169 | param1: z.string().describe("Description of param1"), 170 | param2: z.string().describe("Description of param2"), 171 | option1: z.string().optional().describe("Description of option1"), 172 | option2: z.boolean().optional().describe("Description of option2"), 173 | }), 174 | execute: async (args) => { 175 | return await exampleTool(args.param1, args.param2, { 176 | option1: args.option1, 177 | option2: args.option2, 178 | }); 179 | }, 180 | }, 181 | ]; 182 | ``` 183 | 184 | ### Server Entry Point (src/index.ts) 185 | ```typescript 186 | import { FastMCP } from "fastmcp"; 187 | import { tools } from "./services/tools"; 188 | import { Tool } from "./types/tools"; 189 | 190 | const server = new FastMCP({ 191 | name: "Your Server Name", 192 | version: "1.0.0", 193 | }); 194 | 195 | // Register all tools 196 | tools.forEach((tool) => { 197 | (server.addTool as Tool)(tool); 198 | }); 199 | 200 | // Get transport type from environment variable or default to stdio 201 | const transportType = process.env.TRANSPORT_TYPE || "stdio"; 202 | 203 | if (transportType === "sse") { 204 | server.start({ 205 | transportType: "sse", 206 | sse: { 207 | endpoint: "/sse", 208 | port: parseInt(process.env.PORT || "8080", 10), 209 | }, 210 | }); 211 | } else { 212 | server.start({ 213 | transportType: "stdio", 214 | }); 215 | } 216 | ``` 217 | 218 | ## 4. Testing 219 | 220 | ### Example Test (src/tools/__tests__/example-tool.test.ts) 221 | ```typescript 222 | import exampleTool from "../example-tool"; 223 | 224 | jest.mock("../../config/env", () => ({ 225 | getConfig: jest.fn().mockReturnValue({ 226 | requiredVar: "test-value", 227 | }), 228 | })); 229 | 230 | describe("exampleTool", () => { 231 | beforeEach(() => { 232 | jest.clearAllMocks(); 233 | }); 234 | 235 | it("should handle successful operation", async () => { 236 | const result = await exampleTool("param1", "param2", { option1: "test" }); 237 | expect(result).toBe("Operation successful"); 238 | }); 239 | 240 | it("should throw error when required options are missing", async () => { 241 | await expect( 242 | exampleTool("param1", "param2", {}) 243 | ).rejects.toThrow("Either option1 or option2 must be provided"); 244 | }); 245 | }); 246 | ``` 247 | 248 | ## 5. Best Practices 249 | 250 | ### Error Handling 251 | - Use descriptive error messages 252 | - Implement proper error types 253 | - Handle all potential error cases 254 | - Validate inputs thoroughly 255 | 256 | ### Type Safety 257 | - Use TypeScript strictly 258 | - Define interfaces for all data structures 259 | - Use Zod for runtime validation 260 | - Avoid any type when possible 261 | 262 | ### Testing 263 | - Write unit tests for all tools 264 | - Mock external dependencies 265 | - Test error cases 266 | - Test configuration validation 267 | 268 | ### Configuration 269 | - Use environment variables for configuration 270 | - Validate all required variables 271 | - Provide clear error messages for missing config 272 | - Use TypeScript types for config objects 273 | 274 | ### Code Organization 275 | - Keep tools modular and focused 276 | - Separate concerns (config, tools, services) 277 | - Use consistent naming conventions 278 | - Document public interfaces 279 | 280 | ## 6. Publishing 281 | 282 | 1. Update package.json with your details 283 | 2. Build the project: `npm run build` 284 | 3. Test the build: `npm test` 285 | 4. Publish to npm: `npm publish` 286 | 287 | ## 7. Environment Variables 288 | Create a `.env` file: 289 | ```env 290 | REQUIRED_VARIABLE=your-value 291 | TRANSPORT_TYPE=stdio 292 | PORT=8080 293 | ``` 294 | 295 | Remember to add `.env` to your `.gitignore` file. -------------------------------------------------------------------------------- /init_telegram_openai_agent.md: -------------------------------------------------------------------------------- 1 | # Initializing an AI Chatbot with Telegram and OpenAI Agents SDK 2 | 3 | This guide will walk you through setting up an AI-powered chatbot using Telegram and OpenAI Agents SDK. 4 | 5 | ## Prerequisites 6 | 7 | 1. Python 3.10 or higher 8 | 2. Poetry for dependency management 9 | 3. A Telegram bot token (from @BotFather) 10 | 4. An OpenAI API key 11 | 5. A NewsAPI key (for market news) 12 | 6. A publicly accessible server for webhooks 13 | 14 | ## Project Structure 15 | 16 | ``` 17 | ├── app/ 18 | │ ├── __init__.py 19 | │ ├── main.py # FastAPI app initialization 20 | │ ├── api/ 21 | │ │ ├── __init__.py 22 | │ │ └── telegram_webhook.py # Telegram webhook endpoint 23 | │ └── startup.py # Startup events: register Telegram webhook URL 24 | ├── bot/ 25 | │ ├── __init__.py 26 | │ ├── bot.py # Bot instance and context management 27 | │ ├── agent.py # AI agent implementation 28 | │ ├── context.py # Conversation context and history 29 | │ └── telegram_handler.py # Process incoming messages 30 | ``` 31 | 32 | ## Step 1: Set Up the Project 33 | 34 | 1. Create a new project directory: 35 | ```bash 36 | mkdir my-ai-chatbot 37 | cd my-ai-chatbot 38 | ``` 39 | 40 | 2. Initialize Poetry: 41 | ```bash 42 | poetry init 43 | ``` 44 | 45 | 3. Add required dependencies to `pyproject.toml`: 46 | ```toml 47 | [tool.poetry.dependencies] 48 | python = "^3.10" 49 | fastapi = "^0.115.12" 50 | python-telegram-bot = "^20.8" 51 | uvicorn = "^0.27.1" 52 | python-dotenv = "^1.0.0" 53 | pydantic = "^2.6.1" 54 | openai-agents-python = "^0.1.0" 55 | ``` 56 | 57 | ## Step 2: Create the Context Management 58 | 59 | Create `bot/context.py`: 60 | ```python 61 | from dataclasses import dataclass, field 62 | from datetime import datetime 63 | from typing import List, Optional 64 | 65 | @dataclass 66 | class Message: 67 | timestamp: datetime 68 | sender: str 69 | content: str 70 | 71 | @dataclass 72 | class ChatContext: 73 | user_id: int 74 | current_date: datetime = field(default_factory=datetime.now) 75 | messages: List[Message] = field(default_factory=list) 76 | 77 | def add_message(self, sender: str, content: str) -> None: 78 | self.messages.append(Message( 79 | timestamp=datetime.now(), 80 | sender=sender, 81 | content=content 82 | )) 83 | 84 | def get_conversation_history(self) -> str: 85 | return "\n".join([ 86 | f"{msg.sender}: {msg.content}" 87 | for msg in self.messages 88 | ]) 89 | ``` 90 | 91 | ## Step 3: Create the AI Agent 92 | 93 | Create `bot/agent.py`: 94 | ```python 95 | from agents import Agent, function_tool 96 | 97 | @function_tool 98 | async def search_web(query: str) -> str: 99 | """Search the web for information""" 100 | # Implement your web search logic here 101 | return f"Search results for: {query}" 102 | 103 | # Create the AI agent 104 | ai_agent = Agent( 105 | name="AI Assistant", 106 | instructions=""" 107 | You are an AI assistant powered by OpenAI. Your role is to: 108 | 1. Answer questions accurately and helpfully 109 | 2. Provide relevant information 110 | 3. Maintain context from previous messages 111 | 112 | Your responses should be: 113 | - Clear and concise 114 | - Informative and accurate 115 | - Contextually aware 116 | """, 117 | tools=[search_web], 118 | output_type=str 119 | ) 120 | ``` 121 | 122 | ## Step 4: Set Up the Telegram Bot 123 | 124 | Create `bot/bot.py`: 125 | ```python 126 | import os 127 | import logging 128 | from telegram import Bot 129 | from dotenv import load_dotenv 130 | from bot.context import ChatContext 131 | 132 | logger = logging.getLogger(__name__) 133 | 134 | # Load environment variables 135 | load_dotenv() 136 | 137 | # Get bot token from environment 138 | BOT_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN") 139 | if not BOT_TOKEN: 140 | raise ValueError("TELEGRAM_BOT_TOKEN not set in environment variables") 141 | 142 | # Create bot instance 143 | bot = Bot(token=BOT_TOKEN) 144 | 145 | # Store user contexts 146 | user_contexts = {} 147 | 148 | async def get_user_context(user_id: int) -> ChatContext: 149 | """Get or create a context for a user""" 150 | if user_id not in user_contexts: 151 | user_contexts[user_id] = ChatContext(user_id=user_id) 152 | return user_contexts[user_id] 153 | ``` 154 | 155 | ## Step 5: Create the Message Handler 156 | 157 | Create `bot/telegram_handler.py`: 158 | ```python 159 | import logging 160 | from agents import Runner 161 | from telegram import Update 162 | from bot.bot import bot, get_user_context 163 | from bot.agent import ai_agent 164 | 165 | logger = logging.getLogger(__name__) 166 | 167 | async def handle_telegram_update(update_data: dict): 168 | try: 169 | update = Update.de_json(update_data, bot) 170 | 171 | if update.message: 172 | if update.message.text.startswith('/'): 173 | await handle_command(update) 174 | else: 175 | await handle_message(update) 176 | except Exception as e: 177 | logger.error(f"Error handling Telegram update: {str(e)}") 178 | 179 | async def handle_command(update: Update): 180 | command = update.message.text.split()[0].lower() 181 | 182 | if command == '/start': 183 | await update.message.reply_text("Hello! I'm your AI assistant. How can I help you today?") 184 | elif command == '/help': 185 | await update.message.reply_text(""" 186 | Available commands: 187 | /start - Start the bot 188 | /help - Show this help message 189 | 190 | You can ask me anything, and I'll do my best to help! 191 | """) 192 | 193 | async def handle_message(update: Update): 194 | try: 195 | user_context = await get_user_context(update.message.from_user.id) 196 | user_context.add_message('user', update.message.text) 197 | 198 | result = await Runner.run( 199 | starting_agent=ai_agent, 200 | input=update.message.text, 201 | context=user_context 202 | ) 203 | 204 | response = result.final_output 205 | user_context.add_message('bot', response) 206 | 207 | await update.message.reply_text(response) 208 | except Exception as e: 209 | logger.error(f"Error in handle_message: {str(e)}") 210 | await update.message.reply_text("I'm sorry, I encountered an error. Please try again later.") 211 | ``` 212 | 213 | ## Step 6: Set Up the FastAPI Application 214 | 215 | Create `app/main.py`: 216 | ```python 217 | from fastapi import FastAPI 218 | from fastapi.middleware.cors import CORSMiddleware 219 | from app.api.telegram_webhook import router as telegram_router 220 | from app.startup import startup_event 221 | 222 | app = FastAPI(title="AI Chatbot") 223 | 224 | app.add_middleware( 225 | CORSMiddleware, 226 | allow_origins=["*"], 227 | allow_credentials=True, 228 | allow_methods=["*"], 229 | allow_headers=["*"], 230 | ) 231 | 232 | app.include_router(telegram_router, prefix="/api", tags=["telegram"]) 233 | app.add_event_handler("startup", startup_event) 234 | ``` 235 | 236 | ## Step 7: Create the Webhook Endpoint 237 | 238 | Create `app/api/telegram_webhook.py`: 239 | ```python 240 | from fastapi import APIRouter, Request 241 | from bot.telegram_handler import handle_telegram_update 242 | import logging 243 | 244 | router = APIRouter() 245 | logger = logging.getLogger(__name__) 246 | 247 | @router.post("/telegram/webhook") 248 | async def telegram_webhook(request: Request): 249 | try: 250 | update = await request.json() 251 | await handle_telegram_update(update) 252 | return {"status": "ok"} 253 | except Exception as e: 254 | logger.error(f"Error processing Telegram webhook: {str(e)}") 255 | raise 256 | ``` 257 | 258 | ## Step 8: Set Up Environment Variables 259 | 260 | Create `.env.example`: 261 | ```dotenv 262 | TELEGRAM_BOT_TOKEN=your_bot_token_here 263 | TELEGRAM_WEBHOOK_URL=https://your-domain.com/api/telegram/webhook 264 | HOST=localhost 265 | PORT=8000 266 | ``` 267 | 268 | ## Step 9: Run the Application 269 | 270 | 1. Install dependencies: 271 | ```bash 272 | poetry install 273 | ``` 274 | 275 | 2. Copy `.env.example` to `.env` and fill in your values: 276 | ```bash 277 | cp .env.example .env 278 | ``` 279 | 280 | 3. Start the server: 281 | ```bash 282 | make run 283 | ``` 284 | 285 | ## Step 10: Set Up the Webhook 286 | 287 | 1. Make sure your server is publicly accessible 288 | 2. The webhook will be automatically registered when the application starts 289 | 3. Test your bot by sending it a message 290 | 291 | ## Customization 292 | 293 | You can customize your AI agent by: 294 | 1. Modifying the agent's instructions in `bot/agent.py` 295 | 2. Adding new tools for specific functionality 296 | 3. Adjusting the context management in `bot/context.py` 297 | 4. Enhancing the message handling in `bot/telegram_handler.py` 298 | 299 | ## Best Practices 300 | 301 | 1. Always handle errors gracefully 302 | 2. Implement rate limiting for API calls 303 | 3. Use proper logging for debugging 304 | 4. Keep sensitive information in environment variables 305 | 5. Implement proper security measures for your webhook endpoint 306 | 307 | ## Next Steps 308 | 309 | 1. Add more sophisticated tools to your agent 310 | 2. Implement persistent storage for conversation history 311 | 3. Add user authentication and authorization 312 | 4. Implement analytics and monitoring 313 | 5. Add support for media messages and other Telegram features --------------------------------------------------------------------------------