🧠 MCP Server + Document Memory System

Transform your AI from stateless to intelligent with persistent memory, semantic search, and advanced task capabilities.

🎯 Mission

Build a production-ready MCP Server that enables an AI system to:

• ✅ Remember all user interactions and documents
• ✅ Understand document context and meaning
• ✅ Route requests intelligently (memory-first strategy)
• ✅ Synthesize content from multiple sources
• ✅ Edit documents based on user feedback
• ✅ Create new documents from requirements
• ✅ Execute complex multi-step tasks
• ✅ Learn from every interaction

📊 Project Status

Phase 1: MCP Foundation ✅ COMPLETE

• Base MCP Server framework
• Quality scoring system (7 factors)
• Content router (5 strategies)
• Web search integration
• 33 unit tests (all passing)
• Comprehensive documentation

Phase 2-5: In Progress (Starting soon)

• Document memory & vector DB
• Semantic search
• Document editing/creation
• Advanced task execution
• Testing & deployment

🚀 Quick Start (5 minutes)

1. Clone & Install

cd "c:\Users\DELL CORE i5\New folder\mcp"
pip install -r requirements.txt

2. Configure

copy .env.example .env
# Add your API keys to .env

3. Run

python main.py

4. Test

curl http://localhost:8000/health

📚 Documentation

📁 Key Components

Core Framework

• MCP Server (src/mcp_server/base_server.py): Protocol handler, tool management, resource lifecycle
• Quality Scorer (src/mcp_server/quality_scorer.py): 7-factor content evaluation
• Content Router (src/content_router/router.py): Intelligent source selection
• Web Search Tool (src/web_search/web_search_tool.py): Google Gemini integration

Infrastructure

• Configuration (config/settings.py): Environment-based config
• Logging (config/logging_config.py): Structured logging
• Protocols (src/mcp_protocol.py): Request/response schemas
• Utilities (src/utils.py): Shared types & helpers

Testing (33 tests)

• tests/test_mcp_server.py - Server functionality
• tests/test_quality_scorer.py - Scoring system
• tests/test_content_router.py - Routing logic
• tests/test_web_search.py - Web search tool\

🎯 Key Features

✅ Phase 1: MCP Foundation

Base MCP Server

• Async request/response handling
• Tool registration and discovery
• Middleware support
• Custom error handling
• Resource management lifecycle

Quality Scoring (7 Factors)

• Source reliability (25%)
• Content freshness (15%)
• Relevance (25%)
• Completeness (15%)
• Accuracy (15%)
• Citation count (3%)
• User feedback (2%)

Content Router (5 Strategies)

• MEMORY_FIRST: Check cache first (default)
• EXTERNAL_FIRST: Get latest info
• BALANCED: Comprehensive coverage
• MEMORY_ONLY: Offline mode
• EXTERNAL_ONLY: Fresh data only

Web Search Integration

• Google Gemini API
• Async execution
• Result ranking
• Mock fallback for testing

⏳ Phase 2-5: Advanced Features

Phase 2: Document Memory

• Vector database (ChromaDB + FAISS)
• Document processing (PDF, DOCX, PPTX, HTML, Images)
• Semantic search
• Usage-based optimization

Phase 3: Memory Integration

• Document Memory MCP Server
• Memory-first routing
• Content synthesis
• Performance analytics

Phase 4: Advanced Features

• Document Editor (edit/version control)
• Document Creator (generation from requirements)
• Task Executor (complex operations)
• Feedback integration

Phase 5: Production Ready

• Comprehensive testing (90%+ coverage)
• Performance optimization
• Security hardening
• Docker deployment
• Kubernetes configuration

💻 API Examples

Web Search

curl -X POST http://localhost:8000/request \
  -H "Content-Type: application/json" \
  -d '{
	"request_id": "req_001",
	"method": "execute",
	"tool": "web_search",
	"params": {"query": "AI trends", "limit": 5}
  }'

List Tools

curl http://localhost:8000/tools

Server Health

curl http://localhost:8000/health

Statistics

curl http://localhost:8000/stats

🧪 Testing

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test file
pytest tests/test_quality_scorer.py -v

# Run single test
pytest tests/test_mcp_server.py::test_server_initialization -v

Current Status: 33/33 tests passing ✅

📋 Success Metrics

🔧 Configuration

Key settings in .env:

# Server
ENVIRONMENT=development
MCP_HOST=0.0.0.0
MCP_PORT=8000

# API Keys
GOOGLE_API_KEY=your_key_here

# Performance
VECTOR_SEARCH_K=10
MEMORY_HIT_THRESHOLD=0.7
CACHE_TTL=3600

# Logging
LOG_LEVEL=INFO
DEBUG=True

📚 Learning Path

1. Read: QUICKSTART.md - 10 min
2. Run: python main.py - 5 min
3. Test: pytest tests/ -v - 5 min
4. Explore: ARCHITECTURE_GUIDE.md - 20 min
5. Code: Review src/mcp_server/base_server.py - 30 min
6. Extend: Add custom tool - 30 min

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│         REST API (FastAPI)                      │
│  GET / POST /health /stats /tools /request     │
└────────────────┬────────────────────────────────┘
				 │
		 ┌───────▼────────┐
		 │  MCP Protocol  │
		 │   Processor    │
		 └───────┬────────┘
				 │
	┌────────────┼────────────┐
	│            │            │
	▼            ▼            ▼
┌────────┐  ┌──────────┐  ┌──────────┐
│  Web   │  │ Quality  │  │ Content  │
│ Search │  │ Scorer   │  │ Router   │
│  Tool  │  │  (7x)    │  │(5 modes) │
└────────┘  └──────────┘  └──────────┘
	│            │            │
	└────────────┼────────────┘
				 │
	┌────────────▼────────────┐
	│  Storage Layer (Phase 2+)
	│  - ChromaDB (vectors)
	│  - PostgreSQL (metadata)
	│  - Redis (cache)
	└─────────────────────────┘

🚨 Known Limitations (Phase 1)

• No persistent storage (added in Phase 2)
• No document processing (added in Phase 2)
• No vector database (added in Phase 2)
• No semantic search (added in Phase 2)
• Mock search fallback (real API key needed)
• No authentication (added in Phase 5)

📝 Implementation Timeline

🎓 Code Examples

Creating a Custom Tool

from src.mcp_server import MCPTool, ToolType

class MyTool(MCPTool):
	async def execute(self, params):
		# Your code here
		return {"result": "success"}

# Register and use
mcp_server.register_tool(MyTool(...))

Using Quality Scorer

from src.mcp_server import quality_scorer

score = quality_scorer.score_content(
	content="...",
	source_type="memory",
	created_at=datetime.utcnow(),
	relevance_score=0.8
)
# Returns: overall_score, quality_level, components

Content Routing

from src.content_router import content_router, RoutingStrategy

decision = await content_router.route_request(
	query="AI trends",
	strategy=RoutingStrategy.MEMORY_FIRST
)
# Returns: sources_to_query, expected_quality, reasoning

📞 Support

• Quick Questions: See QUICKSTART.md
• How It Works: See ARCHITECTURE_GUIDE.md
• Detailed Docs: See PHASE1_DOCUMENTATION.md
• Tests: Run pytest tests/ -v for examples
• Logs: Check logs/app.log for troubleshooting

🎯 Next Steps

1. Install and run the server
2. Run test suite (pytest tests/ -v)
3. Try API examples (see QUICKSTART.md)
4. Read architecture guide
5. Extend with custom tools
6. Phase 2: Add document memory & vectors

📄 License

MIT - See LICENSE file (to be added)

👥 Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit pull request

Built with Python 3.11+, FastAPI, ChromaDB, Docling

Phase 1 Complete! Ready for Phase 2: Document Memory 🚀

mcp