{"id":36672261,"url":"https://github.com/captain-corgi/vcd-crewai-windsurf-example","last_synced_at":"2026-01-12T10:42:42.773Z","repository":{"id":305266003,"uuid":"1022420272","full_name":"captain-corgi/vcd-crewai-windsurf-example","owner":"captain-corgi","description":"Vibe Coding CrewAI example craft with Windsurf","archived":false,"fork":false,"pushed_at":"2025-08-16T09:06:48.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-16T11:25:47.078Z","etag":null,"topics":["crewai","vibe-coding","windsurf-ai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/captain-corgi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-19T03:32:24.000Z","updated_at":"2025-08-16T09:06:52.000Z","dependencies_parsed_at":"2025-07-19T09:04:48.992Z","dependency_job_id":null,"html_url":"https://github.com/captain-corgi/vcd-crewai-windsurf-example","commit_stats":null,"previous_names":["captain-corgi/vcd-crewai-windsurf-example"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/captain-corgi/vcd-crewai-windsurf-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captain-corgi%2Fvcd-crewai-windsurf-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captain-corgi%2Fvcd-crewai-windsurf-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captain-corgi%2Fvcd-crewai-windsurf-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captain-corgi%2Fvcd-crewai-windsurf-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/captain-corgi","download_url":"https://codeload.github.com/captain-corgi/vcd-crewai-windsurf-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/captain-corgi%2Fvcd-crewai-windsurf-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:40:25.642Z","status":"ssl_error","status_checked_at":"2026-01-12T10:39:27.820Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["crewai","vibe-coding","windsurf-ai"],"created_at":"2026-01-12T10:42:41.726Z","updated_at":"2026-01-12T10:42:42.762Z","avatar_url":"https://github.com/captain-corgi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CrewAI Notion Chatbot\n\nA sophisticated chatbot powered by CrewAI that can answer questions about your Notion workspace using MCP (Model Context Protocol) integration.\n\n## Features\n\n- 🤖 **CrewAI Integration**: Uses multiple specialized AI agents working together\n- 📚 **Notion Connectivity**: Direct integration with Notion API for real-time data access\n- 🔗 **MCP Support**: Compatible with CrewAI Enterprise MCP server for production deployments\n- 🎯 **Intelligent Agents**: Specialized agents for research, Q\u0026A, and conversation management\n- 💬 **Multiple Interfaces**: Both CLI and Streamlit web interface\n- 🧠 **Memory**: Maintains conversation context and history\n- 🔄 **Fallback System**: Automatically falls back to local crews if MCP is unavailable\n\n## Architecture\n\nThe chatbot uses a multi-agent system with the following components:\n\n### Agents\n\n1. **Notion Researcher**: Searches and retrieves information from Notion\n2. **Q\u0026A Specialist**: Synthesizes information into comprehensive answers\n3. **Conversation Manager**: Manages conversation flow and context\n4. **MCP Coordinator**: Handles CrewAI Enterprise deployments\n\n### Tools\n\n- **NotionSearchTool**: Search across Notion workspace\n- **NotionPageRetrieverTool**: Retrieve specific page content\n- **NotionDatabaseQueryTool**: Query Notion databases\n\n### Integration\n\n- **Local CrewAI**: Runs crews locally for development and testing\n- **MCP Integration**: Connects to CrewAI Enterprise for production deployments\n- **Fallback System**: Seamlessly switches between MCP and local execution\n\n## Prerequisites\n\n- Python 3.10 or higher (but less than 3.14)\n- OpenAI API key\n- Notion integration token\n- (Optional) CrewAI Enterprise account for MCP features\n\n## Installation\n\n1. **Clone the repository**:\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd vcd-crewai-windsurf-example\n   ```\n\n2. **Install dependencies**:\n\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up environment variables**:\n\n   ```bash\n   cp .env.example .env\n   ```\n\n4. **Configure your `.env` file**:\n\n   ```env\n   # Required\n   OPENAI_API_KEY=your_openai_api_key_here\n   NOTION_TOKEN=your_notion_integration_token_here\n   \n   # Optional (for MCP integration)\n   MCP_CREWAI_ENTERPRISE_SERVER_URL=https://app.crewai.com\n   MCP_CREWAI_ENTERPRISE_BEARER_TOKEN=your_bearer_token_here\n   \n   # Optional (for specific database queries)\n   NOTION_DATABASE_ID=your_notion_database_id_here\n   ```\n\n## Notion Setup\n\n### 1. Create a Notion Integration\n\n1. Go to [https://www.notion.so/my-integrations](https://www.notion.so/my-integrations)\n2. Click \"New integration\"\n3. Give it a name (e.g., \"CrewAI Chatbot\")\n4. Select your workspace\n5. Copy the \"Internal Integration Token\"\n\n### 2. Share Pages with Your Integration\n\n1. Open the Notion pages you want the chatbot to access\n2. Click \"Share\" in the top-right corner\n3. Click \"Invite\" and select your integration\n4. Grant appropriate permissions\n\n### 3. (Optional) Get Database IDs\n\nIf you want to query specific databases:\n\n1. Open the database in Notion\n2. Copy the URL - the database ID is the long string after the last `/`\n3. Add it to your `.env` file as `NOTION_DATABASE_ID`\n\n## Usage\n\n### CLI Interface\n\nRun the chatbot in command-line mode:\n\n```bash\npython main.py\n```\n\nExample interaction:\n\n```\nYou: What projects are currently in progress?\n🤔 Thinking...\n🤖 Assistant: Based on your Notion workspace, here are the current projects...\n```\n\n### Streamlit Web Interface\n\nLaunch the web interface:\n\n```bash\nstreamlit run src/streamlit_app.py\n```\n\nThen open your browser to `http://localhost:8501`\n\nThe web interface provides:\n\n- Interactive chat interface\n- Environment status monitoring\n- MCP connection status\n- Conversation history management\n- Debug information\n\n### Example Questions\n\nTry asking questions like:\n\n- \"What are my current tasks?\"\n- \"Show me information about the project roadmap\"\n- \"What meetings do I have scheduled?\"\n- \"Find pages about the marketing campaign\"\n- \"What's in my personal notes database?\"\n\n## MCP Integration (Optional)\n\n### CrewAI Enterprise Setup\n\n1. **Sign up for CrewAI Enterprise**:\n   - Visit [https://app.crewai.com](https://app.crewai.com)\n   - Create an account and get your bearer token\n\n2. **Deploy your crews**:\n   - Upload your crew configurations to the platform\n   - Note the crew IDs for your deployments\n\n3. **Configure MCP**:\n   - Set `MCP_CREWAI_ENTERPRISE_BEARER_TOKEN` in your `.env`\n   - The chatbot will automatically use MCP when available\n\n### Local Development\n\nWhen MCP is not configured or unavailable:\n\n- The chatbot automatically falls back to local CrewAI execution\n- All functionality remains available\n- Performance may be slower but no external dependencies required\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | Yes | Your OpenAI API key |\n| `NOTION_TOKEN` | Yes | Notion integration token |\n| `MCP_CREWAI_ENTERPRISE_SERVER_URL` | No | MCP server URL (default: \u003chttps://app.crewai.com\u003e) |\n| `MCP_CREWAI_ENTERPRISE_BEARER_TOKEN` | No | CrewAI Enterprise bearer token |\n| `NOTION_DATABASE_ID` | No | Specific database ID to query |\n| `CREWAI_TELEMETRY_OPT_OUT` | No | Set to `true` to disable telemetry |\n\n### Crew Configuration\n\nThe chatbot uses these crew configurations:\n\n- **Sequential Process**: Agents work in sequence for thorough analysis\n- **Memory Enabled**: Maintains context across conversations\n- **Embedding Model**: Uses OpenAI text-embedding-3-small for memory\n\n## File Structure\n\n```\nvcd-crewai-windsurf-example/\n├── src/\n│   ├── __init__.py\n│   ├── agents.py              # CrewAI agent definitions\n│   ├── crews.py               # Crew configurations and main chatbot class\n│   ├── mcp_client.py          # MCP client and simulator\n│   ├── notion_tools.py        # Notion API integration tools\n│   └── streamlit_app.py       # Streamlit web interface\n├── docs/\n│   └── init_prompt.md         # Project initialization prompt\n├── main.py                    # CLI entry point\n├── requirements.txt           # Python dependencies\n├── .env.example              # Environment variable template\n└── README.md                 # This file\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"Missing required environment variables\"**\n   - Ensure `.env` file is created and configured\n   - Check that API keys are valid and not placeholder values\n\n2. **\"Error searching Notion\"**\n   - Verify your Notion integration token is correct\n   - Ensure pages are shared with your integration\n   - Check your internet connection\n\n3. **\"MCP Disconnected\"**\n   - This is normal if you haven't configured CrewAI Enterprise\n   - The chatbot will use local crews automatically\n   - For MCP features, ensure your bearer token is valid\n\n4. **\"Error executing local crew\"**\n   - Check your OpenAI API key is valid and has credits\n   - Ensure all dependencies are installed correctly\n   - Try restarting the application\n\n### Debug Mode\n\nEnable debug information in the Streamlit interface:\n\n1. Check \"Show Debug Information\" at the bottom of the page\n2. Review environment variables and conversation history\n3. Check the console for detailed error messages\n\n## Development\n\n### Adding New Tools\n\n1. Create a new tool class in `src/notion_tools.py`\n2. Inherit from `BaseTool`\n3. Implement the `_run` method\n4. Add to the appropriate agent in `src/agents.py`\n\n### Customizing Agents\n\n1. Modify agent configurations in `src/agents.py`\n2. Adjust roles, goals, and backstories\n3. Add or remove tools as needed\n4. Update crew configurations in `src/crews.py`\n\n### Testing\n\nRun the test script to validate functionality:\n\n```bash\npython test_chatbot.py\n```\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Support\n\nFor issues and questions:\n\n- Check the troubleshooting section\n- Review the CrewAI documentation\n- Check Notion API documentation\n- Open an issue on GitHub\n\n## Acknowledgments\n\n- [CrewAI](https://github.com/crewAIInc/crewAI) - Multi-agent framework\n- [Notion API](https://developers.notion.com/) - Notion integration\n- [Streamlit](https://streamlit.io/) - Web interface\n- [OpenAI](https://openai.com/) - Language models\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptain-corgi%2Fvcd-crewai-windsurf-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaptain-corgi%2Fvcd-crewai-windsurf-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaptain-corgi%2Fvcd-crewai-windsurf-example/lists"}