Content
# MCP Data Visualization & Experimentation Platform
A comprehensive project for experimenting with the **Model Context Protocol (MCP)** and modern Large Language Models (LLMs) like GPT-4o, Claude 3, and Llama 3.
## 🎯 What is Model Context Protocol (MCP)?
The Model Context Protocol (MCP) is an open standard that enables seamless integration between AI applications and data sources. It allows LLMs to securely access and interact with various tools, databases, APIs, and services in real-time.
### Key Benefits of MCP:
- **Secure Tool Access**: Controlled, permission-based access to external resources
- **Real-time Data**: LLMs can access live data instead of relying on training cutoffs
- **Extensibility**: Easy to add new tools and capabilities
- **Standardization**: Consistent interface across different AI providers
- **Privacy**: Data stays within your control and infrastructure
## 🏗️ Project Architecture
```
mcp-data-vis/
├── src/
│ ├── servers/ # MCP Server implementations
│ │ ├── filesystem/ # File operations server
│ │ ├── database/ # Database query server
│ │ ├── web-scraper/ # Web scraping & API server
│ │ └── calculator/ # Mathematical operations server
│ ├── client/ # MCP Client applications
│ │ ├── cli/ # Command-line interface
│ │ └── web/ # Web dashboard
│ └── lib/ # Shared utilities
├── examples/ # Practical use case examples
├── tests/ # Test suites
├── docs/ # Documentation
└── scripts/ # Setup and utility scripts
```
## ⚠️ Setup Status
**Current Status**: Core platform complete with some SDK compatibility issues. See [SETUP_STATUS.md](SETUP_STATUS.md) for details.
- ✅ **All MCP servers implemented** (filesystem, database, web-scraper, calculator)
- ✅ **Complete documentation and examples**
- ✅ **Unit tests passing**
- ⚠️ **Integration tests need Node.js 20+** for full compatibility
## 🚀 Quick Start
### Prerequisites
- Node.js 20.18.1+ (recommended) or 18+ (limited compatibility)
- npm or yarn
- SQLite3 (for database examples)
### Installation
```bash
# Clone and setup
git clone <repository-url>
cd mcp-data-vis
npm install
npm run setup
# Start all servers and client
npm run dev
# Or start individual components
npm run server:fs # Filesystem server
npm run server:db # Database server
npm run server:web # Web scraper server
npm run client:cli # CLI client
```
## 🛠️ MCP Servers Included
### 1. Filesystem Server (`/src/servers/filesystem/`)
**Use Cases**: File management, document processing, log analysis
**Capabilities**:
- Read/write files and directories
- Search file contents
- File metadata analysis
- Batch file operations
**Example Tools**:
```javascript
// Available MCP tools
- read_file(path)
- write_file(path, content)
- list_directory(path)
- search_files(pattern, directory)
- get_file_stats(path)
```
### 2. Database Server (`/src/servers/database/`)
**Use Cases**: Data analysis, reporting, business intelligence
**Capabilities**:
- SQL query execution
- Schema introspection
- Data visualization preparation
- Performance monitoring
**Example Tools**:
```javascript
// Available MCP tools
- execute_query(sql)
- get_schema()
- get_table_info(table_name)
- create_table(schema)
- bulk_insert(table, data)
```
### 3. Web Scraper Server (`/src/servers/web-scraper/`)
**Use Cases**: Market research, content analysis, API integration
**Capabilities**:
- Web page scraping
- REST API calls
- Content extraction
- Rate-limited requests
**Example Tools**:
```javascript
// Available MCP tools
- scrape_page(url, selectors)
- api_request(url, method, headers, data)
- extract_links(url)
- get_page_metadata(url)
```
### 4. Calculator Server (`/src/servers/calculator/`)
**Use Cases**: Mathematical analysis, data processing, scientific computing
**Capabilities**:
- Complex mathematical operations
- Statistical analysis
- Data transformations
- Unit conversions
**Example Tools**:
```javascript
// Available MCP tools
- calculate(expression)
- statistical_analysis(data)
- matrix_operations(operation, matrices)
- unit_conversion(value, from_unit, to_unit)
```
## 💻 Client Applications
### CLI Client (`/src/client/cli/`)
Interactive command-line interface for testing MCP servers:
```bash
npm run client:cli
# Interactive mode
> connect filesystem
> read_file data/sample.txt
> calculate 2 + 2 * 3
> scrape_page https://example.com
```
### Web Dashboard (`/src/client/web/`)
Browser-based interface with:
- Server management
- Tool testing interface
- Results visualization
- Performance monitoring
```bash
cd src/client/web
npm install
npm run dev
# Open http://localhost:3000
```
## 📊 Practical Examples
### Example 1: Data Analysis Pipeline
```javascript
// Combine multiple MCP servers for data analysis
import { MCPClient } from './src/lib/mcp-client.js';
const client = new MCPClient();
// 1. Read CSV data
const data = await client.callTool('filesystem', 'read_file', {
path: 'data/sales.csv'
});
// 2. Store in database
await client.callTool('database', 'bulk_insert', {
table: 'sales',
data: parseCSV(data)
});
// 3. Analyze trends
const results = await client.callTool('database', 'execute_query', {
sql: 'SELECT month, SUM(amount) FROM sales GROUP BY month'
});
// 4. Calculate statistics
const stats = await client.callTool('calculator', 'statistical_analysis', {
data: results.map(r => r.amount)
});
```
### Example 2: Content Research & Analysis
```javascript
// Research competitor pricing
const pages = await client.callTool('web-scraper', 'scrape_page', {
url: 'https://competitor.com/pricing',
selectors: {
prices: '.price',
features: '.feature-list'
}
});
// Store findings
await client.callTool('filesystem', 'write_file', {
path: 'research/competitor-analysis.json',
content: JSON.stringify(pages, null, 2)
});
// Calculate price comparisons
const comparison = await client.callTool('calculator', 'calculate', {
expression: `(${pages.prices.join(' + ')}) / ${pages.prices.length}`
});
```
### Example 3: Automated Reporting
```javascript
// Generate daily report
const logs = await client.callTool('filesystem', 'search_files', {
pattern: '*.log',
directory: '/var/logs'
});
const errors = await client.callTool('database', 'execute_query', {
sql: 'SELECT COUNT(*) as error_count FROM logs WHERE level = "ERROR"'
});
const report = await client.callTool('filesystem', 'write_file', {
path: `reports/daily-${new Date().toISOString().split('T')[0]}.md`,
content: generateReport(logs, errors)
});
```
## 🧪 Testing
```bash
# Run all tests
npm test
# Unit tests only
npm run test:unit
# Integration tests only
npm run test:integration
# Test specific server
npm test -- --grep "filesystem"
```
## 🔧 Development
### Adding New MCP Servers
1. Create server directory: `src/servers/my-server/`
2. Implement MCP server interface:
```javascript
// src/servers/my-server/server.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
const server = new Server(
{
name: "my-server",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
// Add tool handlers
server.setRequestHandler(ToolRequestSchema, async (request) => {
// Implementation
});
// Start server
server.connect(transport);
```
3. Add to package.json scripts
4. Create tests in `tests/unit/servers/my-server/`
### Adding New Tools
```javascript
// In your server implementation
server.setRequestHandler(ToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
switch (name) {
case "my_new_tool":
return {
content: [
{
type: "text",
text: await myNewToolImplementation(args)
}
]
};
}
});
```
## 📚 Best Practices
### Security
- Always validate inputs
- Use environment variables for secrets
- Implement rate limiting
- Sanitize file paths and SQL queries
### Performance
- Cache frequently accessed data
- Use connection pooling for databases
- Implement request batching
- Monitor resource usage
### Error Handling
- Provide meaningful error messages
- Log errors for debugging
- Implement graceful degradation
- Use circuit breakers for external services
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## 📖 Resources
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [Example Servers](https://github.com/modelcontextprotocol/servers)
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
