# BC Calculator MCP Server - Project Summary
## What We're Building
A production-ready MCP server that provides arbitrary precision mathematical calculations using the Unix `bc` calculator, with enterprise-grade security, performance, and reliability.
## 📋 Planning Documents Created
1. **[ARCHITECTURE.md](ARCHITECTURE.md)** - System Design (583 lines)
- Complete component architecture
- Security model
- Process management flow
- Mermaid diagrams
2. **[IMPLEMENTATION_GUIDE.md](IMPLEMENTATION_GUIDE.md)** - Developer Guide (688 lines)
- Step-by-step implementation
- Code skeletons for all files
- Testing strategy
- Deployment instructions
3. **[README.md](README.md)** - User Documentation (429 lines)
- Installation guide
- Usage examples
- API reference
- Troubleshooting
4. **[QUICK_REFERENCE.md](QUICK_REFERENCE.md)** - Cheat Sheet (373 lines)
- Security checklist
- Code patterns
- Testing checklist
- Common fixes
## 🏗️ Architecture Overview
```
┌─────────────────────────────────────────────────┐
│ BC Calculator MCP Server │
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ MCP Server (index.ts) │ │
│ │ • Tool: calculate │ │
│ │ • Tool: calculate_advanced │ │
│ │ • Tool: set_precision │ │
│ └────────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────▼───────────────────────────────┐ │
│ │ Input Validator (input-validator.ts) │ │
│ │ • Security: Whitelist/Blacklist │ │
│ │ • Max length: 10KB │ │
│ │ • No command injection │ │
│ └────────────┬───────────────────────────────┘ │
│ │ │
│ ┌────────────▼───────────────────────────────┐ │
│ │ BC Process Pool (bc-process-pool.ts) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ BC Proc │ │ BC Proc │ │ BC Proc │ │ │
│ │ │ #1 │ │ #2 │ │ #3 │ │ │
│ │ │ Ready │ │ Busy │ │ Ready │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └────────────────────────────────────────────┘ │
│ │
│ Each process (bc-process.ts): │
│ • Spawned with -l flag (math library) │
│ • Precision: 20 decimals (configurable) │
│ • Timeout: 30 seconds │
│ • Auto-respawn on crash │
└─────────────────────────────────────────────────┘
```
## 🔐 Security Design
**Multi-Layer Protection**:
1. **Input Validation Layer**
- Character whitelist: `[0-9a-zA-Z+\-*\/^().,;\s=<>!&|%{}[\]]`
- Blacklist patterns: `system()`, `exec()`, backticks, pipes, redirects
- Maximum expression length: 10,000 characters
2. **Process Isolation Layer**
- No shell execution (`shell: false`)
- Direct BC binary spawn
- Separate process per calculation
3. **Resource Protection Layer**
- 30-second timeout per calculation
- Process pool size limit (3)
- Automatic cleanup on timeout/failure
## 📁 File Structure
```
/home/travis/.local/share/Roo-Code/MCP/bc-calculator/
├── package.json # Dependencies & scripts
├── tsconfig.json # TypeScript config
├── README.md # User docs
├── ARCHITECTURE.md # System design
├── IMPLEMENTATION_GUIDE.md # Dev guide
├── QUICK_REFERENCE.md # Cheat sheet
├── src/
│ ├── types.ts # Type definitions
│ ├── input-validator.ts # Security validation
│ ├── bc-process.ts # Single BC process wrapper
│ ├── bc-process-pool.ts # Process pool manager
│ └── index.ts # MCP server main
└── build/ # Compiled output
└── index.js # Executable server
```
## 🎯 Implementation Roadmap
### Phase 1: Foundation (Todos 1-3)
- Create project directory structure
- Initialize package.json with dependencies
- Configure TypeScript (tsconfig.json)
### Phase 2: Core Components (Todos 4-6, 13)
- Design and implement type definitions
- Build input validator with security rules
- Create BC process wrapper with I/O handling
- Implement process pool manager
### Phase 3: MCP Integration (Todos 7-9)
- Implement `calculate` tool
- Implement `calculate_advanced` tool
- Implement `set_precision` tool
### Phase 4: Error & Resource Management (Todos 10-14)
- Add comprehensive error handling
- Implement timeout mechanism
- Add process recovery logic
- Create request queue system
### Phase 5: Deployment (Todos 15-16)
- Build TypeScript to JavaScript
- Auto-install to MCP settings
- Verify server registration
### Phase 6: Testing & Documentation (Todos 17-20)
- Test basic arithmetic
- Test advanced features
- Write unit tests
- Create final documentation
## 🔧 Technology Stack
| Component | Technology | Purpose |
|-----------|-----------|---------|
| Language | TypeScript 5.3+ | Type safety & modern syntax |
| Runtime | Node.js 18+ | Server execution |
| Protocol | MCP SDK 1.0.4+ | MCP compliance |
| Calculator | bc (GNU) | Arbitrary precision math |
| Process Mgmt | child_process | BC process spawning |
| Validation | Regex + Whitelist | Input security |
## 🚀 Key Features
### Functional
✅ Arbitrary precision (0-100 decimal places)
✅ Basic arithmetic (+, -, *, /, ^, %)
✅ Math library (sqrt, sin, cos, arctan, log, exp)
✅ Variables and assignments
✅ Control flow (if, while, for)
✅ Multi-line scripts
✅ Three concurrent processes
### Non-Functional
✅ Security: Command injection prevention
✅ Performance: <50ms for typical calculations
✅ Reliability: Auto-recovery from crashes
✅ Usability: Clear error messages
✅ Maintainability: Well-documented code
✅ Testability: Comprehensive test suite
## 📊 Expected Performance
| Operation | Target | Notes |
|-----------|--------|-------|
| Simple calc (2+2) | <10ms | Fastest path |
| Division w/ precision | <20ms | Common use case |
| Math functions | <50ms | Using -l library |
| Complex scripts | <200ms | Multi-statement |
| Process spawn | <100ms | One-time cost |
| Concurrent requests | 3 parallel | Pool size limit |
## 🧪 Test Coverage Plan
### Unit Tests
- Input validation edge cases
- Dangerous pattern detection
- Expression sanitization
- Error message formatting
### Integration Tests
- All mathematical operators
- All math library functions
- Variable assignment
- Multi-line scripts
- Precision handling
- Timeout scenarios
- Concurrent requests
- Process failure recovery
### Security Tests
- Command injection attempts
- Shell metacharacter blocking
- File access prevention
- Resource exhaustion
## 📝 Configuration
### MCP Settings Entry
```json
{
"mcpServers": {
"bc-calculator": {
"command": "node",
"args": ["/home/travis/.local/share/Roo-Code/MCP/bc-calculator/build/index.js"],
"disabled": false,
"alwaysAllow": [],
"disabledTools": []
}
}
}
```
### Default Server Config
```typescript
{
poolSize: 3, // Concurrent BC processes
defaultPrecision: 20, // Decimal places
defaultTimeout: 30000, // Milliseconds
maxExpressionLength: 10000 // Characters
}
```
## 🎓 Learning Resources
- **BC Manual**: `man bc` or https://www.gnu.org/software/bc/manual/html_mono/bc.html
- **MCP Docs**: https://modelcontextprotocol.io/
- **Node child_process**: https://nodejs.org/api/child_process.html
- **TypeScript**: https://www.typescriptlang.org/docs/
## ✅ Success Criteria
The implementation will be considered successful when:
1. ✅ All 20 todo items are completed
2. ✅ Server builds without TypeScript errors
3. ✅ Server appears in MCP settings
4. ✅ All three tools are functional
5. ✅ Security validation prevents dangerous inputs
6. ✅ Basic test cases pass
7. ✅ Advanced test cases pass
8. ✅ Concurrent requests work correctly
9. ✅ Error handling works as expected
10. ✅ Documentation is complete
## 📦 Deliverables
1. ✅ Planning documents (this and others)
2. ⏳ Working TypeScript source code
3. ⏳ Compiled JavaScript executable
4. ⏳ MCP configuration entry
5. ⏳ Test suite
6. ⏳ User documentation
7. ⏳ Implementation verification
## 🔄 Next Steps
Once you approve this plan, I will:
1. Switch to **Code Mode**
2. Implement all components according to the architecture
3. Build and test the server
4. Auto-install to MCP settings
5. Verify functionality with test cases
6. Provide usage examples
---
**Ready to proceed?** If you approve this plan, I'll switch to Code mode and begin implementation following the detailed guides in ARCHITECTURE.md and IMPLEMENTATION_GUIDE.md.
