{"id":46613086,"url":"https://github.com/ricard1406/little_mcp","last_synced_at":"2026-03-15T22:26:57.759Z","repository":{"id":320052737,"uuid":"1080620793","full_name":"ricard1406/Little_MCP","owner":"ricard1406","description":"A simple yet powerful local AI assistant that runs entirely on your machine. Built for learning and experimentation, Little MCP combines the power of open-source LLMs with advanced RAG that work with your personal documents. Included tools: real time weather, calculate, local documents RAG, local SQL database","archived":false,"fork":false,"pushed_at":"2026-01-21T18:45:01.000Z","size":275,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-22T05:38:16.780Z","etag":null,"topics":["agent","langchain","mariadb","mcp","mcp-client","mcp-server","mistral","ollama","python","python3","qwen","qwen3","rag","retrieval-augmented-generation","sql","thinking"],"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/ricard1406.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-21T16:14:46.000Z","updated_at":"2026-01-21T18:46:30.000Z","dependencies_parsed_at":"2025-10-21T18:21:01.553Z","dependency_job_id":"2e4e9677-5166-4650-a27e-a3f7a1a92f92","html_url":"https://github.com/ricard1406/Little_MCP","commit_stats":null,"previous_names":["ricard1406/little_mcp"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ricard1406/Little_MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricard1406%2FLittle_MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricard1406%2FLittle_MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricard1406%2FLittle_MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricard1406%2FLittle_MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ricard1406","download_url":"https://codeload.github.com/ricard1406/Little_MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ricard1406%2FLittle_MCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30226785,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T19:01:10.287Z","status":"ssl_error","status_checked_at":"2026-03-07T18:59:58.103Z","response_time":53,"last_error":"SSL_read: 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":["agent","langchain","mariadb","mcp","mcp-client","mcp-server","mistral","ollama","python","python3","qwen","qwen3","rag","retrieval-augmented-generation","sql","thinking"],"created_at":"2026-03-07T19:03:36.733Z","updated_at":"2026-03-15T22:26:57.753Z","avatar_url":"https://github.com/ricard1406.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Little MCP Agent 🤖\n\nA simple yet powerful local AI assistant that runs entirely on your machine. Built for learning and experimentation, Little MCP combines the power of open-source LLMs with advanced Retrieval-Augmented Generation (RAG) to create an intelligent chatbot that can work with your personal documents and provide real-time information.\n\n## ✨ Features\n\n- **Local LLM Integration**: Powered by Ollama for complete privacy and offline functionality\n- **Option: Anthropic LLM Claude**: Required API key\n- **💻 Interface Options**: Graphic web interface or classic text interface.\n- **RAG System**: Query and extract information from your PDF documents using vector embeddings\n- **MCP Server/Client Architecture**: Demonstrates Model Context Protocol implementation with FastAPI\n- **Dual option thinking/ nothinking mode**: show thinking process.\n- **Multi-Tool Agent**: Access to multiple tools including:\n  - Document Q\u0026A system (RAG-based)\n  - local SQL database (Mariadb)\n  - Real-time weather information (OpenWeather API)\n  - Current date and time for any city\n  - Arithmetic calculations\n- **Conversational Memory**: Maintains context throughout your chat session\n- **Vector Store Persistence**: Efficiently stores and reuses document embeddings\n\n## 🔧 Requirements\n\n### System Requirements\n- Python 3.8+\n- [Ollama](https://ollama.ai) installed and running locally\n- OpenWeather API key (free tier available at [openweathermap.org](https://openweathermap.org/api))\n\n\n### Required Ollama Models\nDownload these models before running the application:\n```bash\nollama pull qwen3:4b      (not required when use Claude)\nollama pull nomic-embed-text\n```\n\n## 📦 Installation\n   ## see Installation doc.\n\n\n## 🚀 Usage\n\n### Step 1: Start the MCP Server\n\nIn your first terminal:\n```bash\npython mcp_server.py\n```\n\nYou should see:\n```\nStarting MCP Server ...\nINFO:     Uvicorn running on http://127.0.0.1:8000\n```\n\n### Step 2: Start the MCP Client\n\nIn a second terminal:\n```bash\n[activate your env if not jet] : source ../.venv/bin/activate]\n\n# Local Ollama silent\npython little_mcp.py [graph]\n\n# Local Ollama thinking\npython little_mcp.py --think [graph]\n\n# Use Claude (API key required)\npython little_mcp.py --provider anthropic [graph]\n\n# Use Claude with thinking mode\npython little_mcp.py --provider anthropic --think [graph]\n\n# Override Claude model\npython little_mcp.py --provider anthropic --model claude-opus-4-5 [--think]\n\nnote: add graph parameter for graphical interface\nWhen use graph interface open your browser and run local URL:\nhttp://127.0.0.1:7860\n```\n\n### Step 3: Start Chatting!\n\n```\nYou: What's the weather in Paris?\nYou: What time is it in Tokyo?\nYou: What information is in my document about candidates?\nYou: Calculate ADD, 15, 27\n```\n\n### Step 4: Exit\n\nType `quit`, `exit`, or `bye` to close the client application.\n\n## 🏗️ Architecture\n\n### MCP Server (`mcp_server.py`)\n\nThe FastAPI-based server provides RESTful endpoints for various tools:\n\n**DateTime Tool:**\n- Uses Nominatim for geocoding city names\n- Determines timezone using TimezoneFinder\n- Returns current date, time, and day of week\n\n**Weather Tool:**\n- Integrates with OpenWeather API\n- Returns current weather conditions in metric units\n- Includes temperature, humidity, and weather description\n\n**Calculator Tool:**\n- Supports basic arithmetic operations (ADD, SUB, MUL, DIV)\n- Input format: `\"OPERATION, NUM1, NUM2\"`\n- Example: `\"ADD, 5, 3\"` returns `8`\n\n### MCP Client (`little_mcp.py`)\n\nThe LangChain-based client orchestrates multiple components:\n\n**RAG System:**\n1. Loads your PDF document using PyPDFLoader\n2. Splits the document into manageable chunks\n3. Converts chunks into vector embeddings using Ollama's nomic-embed-text model\n4. Stores embeddings in a Chroma vector database\n5. Retrieves relevant context when you ask questions\n6. Generates answers using the LLM with retrieved context\n\n**Agent Architecture:**\n- Analyzes your queries to determine the best tool to use\n- Routes questions about your document to the RAG system\n- Uses MCP server tools for real-time information\n- Falls back to general knowledge when no tool is suitable\n- Maintains conversation history for context-aware responses\n\n## 🔄 Customization\n\n### Change the LLM Model\nEdit the `LLM` constant in `little_mcp.py`:\n```python\nLLM = \"llama2\"  # or mistral, mixtral, phi, etc.\n```\n\n### Add More MCP Tools\n\n**Server Side** (`mcp_server.py`):\n1. Create your tool function:\n```python\ndef get_my_tool(param: str):\n    # Your logic here\n    return {\"result\": \"data\"}\n```\n\n2. Add an API endpoint:\n```python\n@app.get(\"/get_my_tool\")\ndef api_get_my_tool(myParam: str = Query(...)):\n    result = get_my_tool(myParam)\n    return result\n```\n\n**Client Side** (`little_mcp.py`):\n\nAdd to the `mcp_tools_config` list:\n```python\n{\n    \"name\": \"my_tool\",\n    \"description\": \"Description for the agent to understand when to use this tool\",\n    \"function_name\": \"get_my_tool\"\n}\n```\n\n### Adjust RAG Parameters\n\nModify in `little_mcp.py`:\n```python\n# Number of document chunks to retrieve\nretriever = self.vector_store.as_retriever(search_kwargs={'k': 3})\n\n# Chunk size and overlap\ntext_splitter = RecursiveCharacterTextSplitter(\n    chunk_size=1000, \n    chunk_overlap=200\n)\n```\n\n## 🗂️ Project Structure\n\n```\nLittle_MCP/\n├── mcp_server.py          # FastAPI MCP server\n├── little_mcp.py          # LangChain client application\n├── data/                  # PDF documents directory\n├── chroma_db_rag/         # Vector store (auto-generated)\n├── .env                   # Environment variables (API keys)\n├── requirements.txt       # Python dependencies\n└── README.md             # This file\n```\n\n## 🐛 Troubleshooting\n\n**Server won't start:**\n- Check if port 8000 is already in use\n- Verify your `.env` file contains the API key\n\n**Weather tool fails:**\n- Confirm your OpenWeather API key is valid and active\n- Check your internet connection\n\n**Vector store issues:**\n- Delete the `chroma_db_rag` directory to rebuild from scratch\n\n**Ollama connection errors:**\n- Ensure Ollama is running (`ollama serve`)\n- Verify models are downloaded (`ollama list`)\n\n**PDF not found:**\n- Verify the path in `PDF_DOCUMENT_PATH`\n- Ensure the file exists in the `data` directory\n\n**Client can't connect to server:**\n- Confirm the server is running on port 8000\n- Check the `SERVER_URL` configuration\n\n## 📋 Example Interactions\n\n```\nYou: What's the weather in London?\nAssistant: The current weather in London is 12°C with light rain...\n\nYou: What time is it in New York?\nAssistant: In New York, it's currently 2024-10-22 14:30:15 (Tuesday)...\n\nYou: Calculate ADD, 25, 17\nAssistant: 42.0\n\nYou: What does my document say about candidate scores?\nAssistant: Based on the document, the candidates have the following scores...\n```\n\n## 🤝 Contributing\n\nContributions are welcome! This project is designed for learning and experimentation. Feel free to:\n- Add new tools and capabilities\n- Improve the RAG system\n- Enhance the agent's reasoning\n- Add support for more document types\n- Implement additional MCP endpoints\n\n## 📄 License\n\nMIT License\n\nCopyright (c) 2025\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n## 🙏 Acknowledgments\n\nBuilt with:\n- [LangChain](https://github.com/langchain-ai/langchain) - Agent framework\n- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework for APIs\n- [Ollama](https://ollama.ai) - Local LLM runtime\n- [ChromaDB](https://www.trychroma.com/) - Vector database\n- [OpenWeatherMap](https://openweathermap.org/) - Weather data API\n- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) - Communication standard\n\n---\n\n**Version**: 0.1.01\n\nMade with ❤️ for AI learning and experimentation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricard1406%2Flittle_mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fricard1406%2Flittle_mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fricard1406%2Flittle_mcp/lists"}