Content
# MCP LLM Generator v2 🤖
[](https://badge.fury.io/js/%40mako10k%2Fmcp-llm-generator)
[](https://github.com/mako10k/mcp-sampler/actions/workflows/ci.yml)
[](https://github.com/mako10k/mcp-sampler/actions/workflows/publish.yml)
[](https://opensource.org/licenses/MIT)
🚀 **Production-ready Model Context Protocol (MCP) server** with advanced LLM text generation, context memory management, intelligent template systems, and **Sprint3 Process Quality Foundation**.
> **Sprint3 Achievements**: ✅ Definition of Done v2.0 compliance, ✅ Comprehensive automated testing, ✅ CI/CD pipeline with quality gates, ✅ Full documentation suite, ✅ Operations manual with 24/7 procedures.
## 🎯 Sprint3 Process Quality Foundation
**Complete automation and quality assurance for enterprise-grade MCP operations:**
### 📊 Quality Gates & Automation
- **🎯 Definition of Done v2.0**: Automated compliance checking with 8-category validation
- **🔌 MCP Integration Testing**: 15-test comprehensive protocol validation
- **🚀 CI/CD Pipeline**: Multi-platform testing, security scanning, automated deployment
- **📋 Operations Manual**: 24/7 procedures for maintenance, troubleshooting, and emergency response
- **🏗️ System Architecture**: Complete technical documentation with deployment patterns
### 🔄 Continuous Quality Assurance
```bash
# Automatic quality validation (included in CI/CD)
./scripts/dod-check.sh # Definition of Done v2.0 compliance
./scripts/mcp-integration-test.sh # MCP protocol validation
# Manual quality verification
npm run build # TypeScript compilation
npm run lint # Code quality
npm audit # Security scan
```
## ✨ Key Features
### 🔧 Core Tools
- **`llm-generate`** - Direct LLM text generation via MCP sampling protocol
- **`template-execute`** - Execute sophisticated templates with smart parameter substitution
- **`template-manage`** - Full CRUD operations for reusable prompt templates
- **`context-chat`** - Personality-driven conversations with persistent memory
- **`context-manage`** - Create, update, and manage AI consultant contexts
- **`memory-store`** - Store and organize knowledge with associative linking
### 🧪 Experimental Features (v1.3.0+)
- **`capability-get-self-awareness`** - AI personas recognize their own capabilities (Step3)
- **`capability-get-other-awareness`** - AI personas observe and evaluate other personas
- **`capability-process-inheritance`** - Manage capability inheritance between personas
- **`capability-get-matrix`** - Generate capability matrix for multiple personas
- **`capability-analyze-hierarchy`** - Analyze capability distribution across persona hierarchies
> ⚠️ **Experimental Notice**: The Step3 capability awareness system is an experimental feature under active development. The interface and functionality may change in future versions.
### 📚 Smart Resources
- **`template-list`** - Dynamic discovery of available templates
- **`template-detail`** - Comprehensive template information with validation
- **`context-history`** - Access conversation histories and consultant insights
### 🎯 Advanced Prompts
- **`explain-template`** - Multi-style explanations (beginner, technical, expert)
- **`review-template`** - Intelligent code review and analysis
- **`consultant-prompt`** - Access to 12+ specialized AI consultants
## 🚀 Quick Start
### ⚡ Global Installation (Recommended for Production)
```bash
# Install globally for enterprise deployment
npm install -g @mako10k/mcp-llm-generator
# Verify installation with health check
mcp-llm-generator --version
mcp-llm-generator --health-check # Sprint3 health validation
```
### 🛠️ Local Development Setup (Sprint3 Enhanced)
```bash
# Clone with full Sprint3 development environment
git clone https://github.com/mako10k/mcp-sampler.git
cd mcp-sampler
# Install dependencies with integrity check
npm ci
# Run Sprint3 development setup
npm run dev # Development server with watch mode
./scripts/dod-check.sh # Quality gate validation
./scripts/mcp-integration-test.sh # MCP protocol testing
```
# Build TypeScript with quality validation
npm run build
# Start the server with health monitoring
npm start
# Sprint3 Quality Validation
./scripts/dod-check.sh # Definition of Done v2.0 check
./scripts/mcp-integration-test.sh # MCP protocol validation
```
### 🔌 MCP Client Integration (Sprint3 Enhanced)
**Production Configuration** (Global installation):
```json
{
"servers": {
"mcp-llm-generator": {
"command": "mcp-llm-generator",
"type": "stdio",
"env": {
"LOG_LEVEL": "warn",
"NODE_ENV": "production"
}
}
}
}
```
**Development Configuration** (Local setup):
```json
{
"servers": {
"mcp-llm-generator": {
"command": "node",
"args": ["/path/to/mcp-sampler/build/index.js"],
"type": "stdio",
"env": {
"LOG_LEVEL": "debug",
"NODE_ENV": "development"
}
}
}
}
```
**VS Code MCP Integration** (Recommended):
```json
{
"servers": {
"llm-generator": {
"command": "node",
"args": ["build/index.js"],
"type": "stdio"
},
"assoc-memory": { ... },
"mcp-shell-server": { ... },
"google": { ... }
}
}
```
### 🎯 Sprint3 Configuration Validation
```bash
# Validate MCP client configuration
npx @modelcontextprotocol/inspector node build/index.js
# Test VS Code integration
# 1. Open VS Code with MCP configuration
# 2. Restart VS Code
# 3. Test: "Use @llm-generator to explain quantum computing"
# 4. Check: View → Output → Model Context Protocol
```
## 📖 Usage Examples
### 🤖 Basic LLM Text Generation
```typescript
// Generate text with Sprint3 quality monitoring
await client.callTool("llm-generate", {
messages: [
{
role: "user",
content: {
type: "text",
text: "Explain quantum computing in simple terms"
}
}
],
maxTokens: 500,
temperature: 0.7,
provider: "mcp-internal" // Sprint3: Ensures MCP Sampler usage
});
```
### 📝 Template System (Sprint3 Enhanced)
```typescript
// Execute predefined templates with validation
await client.callTool("template-execute", {
templateName: "explain-template",
args: {
topic: "machine learning",
style: "beginner",
audience: "developers"
},
includeContext: "thisServer" // Sprint3: Enhanced context inclusion
});
// Manage templates with CRUD operations
await client.callTool("template-manage", {
action: "add",
template: {
name: "code-review",
systemPrompt: "You are an expert code reviewer...",
userMessage: "Review this code: {code}",
parameters: { code: "Code to review" }
}
});
```
### 🧠 Context Memory & Consultants
```typescript
// Create a specialized consultant
await client.callTool("context-manage", {
action: "create",
name: "Security Expert",
personality: "Expert cybersecurity consultant with 15+ years experience",
maxTokens: 1000,
temperature: 0.3
});
// Chat with consultant
await client.callTool("context-chat", {
contextId: "security-expert-id",
message: "Review this authentication system for vulnerabilities",
maintainPersonality: true
});
// Store important insights
await client.callTool("memory-store", {
content: "JWT tokens should expire within 15 minutes for high-security applications",
scope: "security/authentication",
tags: ["jwt", "security", "best-practices"]
});
```
### 📚 Resource Discovery
```typescript
// List available templates
const templates = await client.readResource({
uri: "mcp-llm-generator://template-list"
});
// Get detailed template information
const template = await client.readResource({
uri: "mcp-llm-generator://template-detail/explain-template"
});
// Access consultant history
const history = await client.readResource({
uri: "mcp-llm-generator://context-history/security-expert-id"
});
```
## 🛡️ Security & Safety
### 🔒 Database File Protection
This project uses SQLite databases containing sensitive data including consultant personalities, conversation histories, and associative memory networks. **These files must never be committed to version control.**
#### Multi-Layer Protection System
- **`.gitignore`** - Prevents database files from being tracked
- **Pre-commit hooks** - Automatically blocks commits containing sensitive files
- **Clear error handling** - Provides immediate feedback on security violations
#### ⚠️ Critical Security Notes
- **Never commit**: `context-memory.db`, `*.db`, `*.db-wal`, `*.db-shm` files
- **Contains**: 12+ consultant personalities, conversation data, memory associations
- **Risk**: Loss of these files means losing valuable AI consultant expertise
#### 🤝 Shared Memory Security Considerations
- **Personal Environment**: Shared memory tools are designed for individual development environments
- **PC Access Control**: Anyone with access to your PC can read/modify shared memories
- **Context Sharing**: If you share your PC, remember that Copilot conversation histories are also accessible
- **Data Sensitivity**: Avoid storing confidential information in shared memories - use for development notes and ideas only
- **persona_id Validation**: Basic existence checks prevent empty IDs but do not provide authentication
- **Recommendation**: For team collaboration with sensitive data, use dedicated collaboration tools with proper access controls
#### 🔧 Secure Development Setup
```bash
# Install with automatic security hooks
npm install
# If you encounter database commit errors:
git reset HEAD context-memory.db
git reset HEAD *.db *.db-wal *.db-shm
# Verify protection is active
npm run lint
```
### 🔐 Production Security Best Practices
- Regular security audits with `npm audit`
- Dependency vulnerability scanning via GitHub Dependabot
- MIT license ensures open-source transparency
- No network access required for core functionality
- Input validation using Zod schemas throughout
## 🏗️ Architecture & Design
### Core Components
- **LLM Integration** - Direct text generation using MCP sampling protocol
- **Template Engine** - Reusable prompt templates with intelligent parameter substitution
- **Context Memory** - Persistent conversation and consultant management
- **Associative Memory** - Smart knowledge linking and discovery
- **Resource Management** - Dynamic access to templates, contexts, and metadata
- **Type Safety** - Full TypeScript implementation with comprehensive Zod validation
### 📊 Performance Optimizations (v2)
- **67% Token Reduction** - Optimized prompt engineering and response formatting
- **Smart Caching** - Template and context caching for improved response times
- **Memory Efficiency** - Associative linking reduces redundant data storage
- **Lazy Loading** - Dynamic resource loading for faster startup times
## 📚 API Reference
### Core Tools
#### `llm-generate`
Generate text using LLM via MCP sampling protocol.
**Parameters:**
- `messages` (required) - Array of conversation messages
- `maxTokens` (optional, default: 500) - Maximum tokens to generate
- `temperature` (optional, default: 0.7) - Sampling temperature (0.0-1.0)
- `systemPrompt` (optional) - Custom system prompt
#### `template-execute`
Execute predefined templates with parameter substitution.
**Parameters:**
- `templateName` (required) - Name of template to execute
- `args` (required) - Object with template parameter values
- `maxTokens` (optional, default: 500) - Token limit
- `temperature` (optional, default: 0.7) - Sampling temperature
#### `context-chat`
Chat with personality-driven consultants with persistent memory.
**Parameters:**
- `contextId` (required) - Unique consultant context identifier
- `message` (required) - User message to send
- `maintainPersonality` (optional, default: true) - Keep consultant personality
#### `memory-store`
Store knowledge with automatic associative linking.
**Parameters:**
- `content` (required) - Content to store
- `scope` (optional, default: "user/default") - Hierarchical organization scope
- `tags` (optional) - Array of descriptive tags
- `category` (optional) - Content category
### Resources
#### `template-list`
**URI**: `mcp-llm-generator://template-list`
Returns dynamic list of all available templates with metadata.
#### `template-detail/{name}`
**URI**: `mcp-llm-generator://template-detail/{templateName}`
Returns comprehensive template information including parameters and validation rules.
#### `context-history/{id}`
**URI**: `mcp-llm-generator://context-history/{contextId}`
Returns conversation history and consultant insights.
## 🔧 Troubleshooting
### Sprint3 Automated Diagnostics
```bash
# Sprint3 comprehensive health check
./scripts/dod-check.sh # Definition of Done v2.0 validation
./scripts/mcp-integration-test.sh # MCP protocol testing
# Quality validation
npm run lint # Code quality check
npm audit # Security vulnerability scan
npm run build # TypeScript compilation check
```
### Common Issues
#### ❌ "Command not found: mcp-llm-generator"
**Solution:**
```bash
# Reinstall globally with Sprint3 verification
npm install -g @mako10k/mcp-llm-generator
mcp-llm-generator --version
# Verify PATH configuration
npm config get prefix
which mcp-llm-generator
```
#### ❌ "Cannot connect to MCP server"
**Sprint3 Enhanced Solutions:**
1. **Verify MCP client configuration** (Production-ready):
```json
{
"command": "mcp-llm-generator",
"type": "stdio",
"env": {
"LOG_LEVEL": "warn",
"NODE_ENV": "production"
}
}
```
2. **Test server with MCP Inspector**:
```bash
npx @modelcontextprotocol/inspector node build/index.js
# Access http://localhost:5173 for interactive testing
```
3. **Sprint3 manual validation**:
```bash
# Basic startup test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node build/index.js
```
4. **Check Node.js compatibility**:
```bash
node --version # Sprint3 requires ≥18.0.0
npm --version # Should be ≥8.0.0
```
#### ❌ "Template not found" errors
**Solutions:**
1. **List available templates**:
```typescript
await client.readResource({ uri: "mcp-llm-generator://template-list" })
```
2. **Add missing template**:
```typescript
await client.callTool("template-manage", {
action: "add",
template: { /* template definition */ }
})
```
3. **Sprint3 template validation**:
```bash
# Check template integrity
sqlite3 context-memory.db "SELECT name, system_prompt FROM templates;"
```
## 📚 Sprint3 Documentation Suite
### 🏗️ System Architecture & Design
- **[System Architecture](docs/system-architecture.md)** - Complete technical architecture documentation
- **[Context Memory Design](docs/context-memory-design.md)** - Memory management system details
- **[API Reference](docs/API.md)** - Comprehensive API documentation
### 📋 Operations & Quality Assurance
- **[Operations Manual](docs/operations-manual.md)** - 24/7 operational procedures
- **[Definition of Done v2.0](docs/definition-of-done-v2.md)** - Quality standards and compliance
- **[Troubleshooting Guide](docs/operations-manual.md#5-troubleshooting)** - Comprehensive problem resolution
### 🔧 Development & Deployment
- **[Development Guide](docs/operations-manual.md#2-development-test-procedures)** - Setup and development workflows
- **[Deployment Guide](docs/operations-manual.md#3-deployment-procedures)** - Production deployment procedures
- **[Security Manual](docs/operations-manual.md#6-security-operations)** - Security operations and best practices
### 🚀 CI/CD & Automation
- **CI/CD Pipeline**: `.github/workflows/ci.yml` - Automated quality gates
- **Release Pipeline**: `.github/workflows/publish.yml` - Automated publishing
- **Semantic Release**: `.github/workflows/semantic-release.yml` - Version management
## 🎯 Sprint3 Achievements Summary
### ✅ Process Quality Foundation Complete
1. **Definition of Done v2.0** - 8-category automated compliance validation
2. **MCP Integration Testing** - 15-test comprehensive protocol validation
3. **CI/CD Pipeline** - Multi-platform automated testing and deployment
4. **Operations Manual** - Complete 24/7 operational procedures
5. **System Architecture** - Full technical documentation
6. **Security Framework** - Comprehensive security operations guide
### 📊 Quality Metrics
- **Test Coverage**: Comprehensive automated validation
- **Security Score**: Zero vulnerabilities (npm audit)
- **TypeScript**: 100% type safety with strict mode
- **Cross-Platform**: Ubuntu, Windows, macOS compatibility
- **Node.js Support**: 18.x, 20.x, 22.x validated
### 🏆 Enterprise Readiness
- **24/7 Operations**: Complete operational procedures
- **Disaster Recovery**: Emergency response procedures
- **Monitoring**: Health checks and performance tracking
- **Maintenance**: Automated and manual procedures
- **Documentation**: Complete technical and operational docs
#### ❌ "Database file locked" errors
**Solutions:**
1. Ensure no other MCP server instances are running
2. Check file permissions:
```bash
ls -la context-memory.db*
chmod 644 context-memory.db
```
#### ❌ "Memory allocation errors"
**Solutions:**
1. Reduce `maxTokens` parameter
2. Clear old conversation history:
```typescript
await client.callTool("conversation-manage", {
action: "clear",
contextId: "your-context-id"
})
```
### 🐛 Debug Mode
Enable detailed logging:
```bash
DEBUG=mcp-llm-generator:* mcp-llm-generator
```
### 📞 Support
- **Issues**: [GitHub Issues](https://github.com/mako10k/mcp-sampler/issues)
- **Security**: See [SECURITY.md](SECURITY.md)
- **Discussions**: [GitHub Discussions](https://github.com/mako10k/mcp-sampler/discussions)
## 🚀 Migration from v1
### Breaking Changes in v2
- **Scoped package name**: `mcp-llm-generator` → `@mako10k/mcp-llm-generator`
- **New tools**: `context-chat`, `context-manage`, `memory-store` require client updates
- **Enhanced templates**: Additional optional parameters for better control
### Migration Steps
1. **Update global installation**:
```bash
npm uninstall -g mcp-llm-generator
npm install -g @mako10k/mcp-llm-generator
```
2. **Update MCP client configuration**:
```json
{
"command": "mcp-llm-generator" // Updated command
}
```
## 🤝 Contributing
We welcome contributions! Sprint3 has established comprehensive development standards:
### Development Setup (Sprint3 Enhanced)
```bash
git clone https://github.com/mako10k/mcp-sampler.git
cd mcp-sampler
npm ci # Secure dependency installation
# Sprint3 development validation
npm run build # TypeScript compilation
./scripts/dod-check.sh # Definition of Done v2.0 check
./scripts/mcp-integration-test.sh # MCP protocol validation
npm run lint # Code quality validation
```
### Code Standards (Sprint3 Compliance)
- **TypeScript**: Full type safety with strict mode + Sprint3 quality gates
- **ESLint**: Code quality with automated Sprint3 validation
- **Security**: Zero vulnerabilities (npm audit required)
- **Testing**: Comprehensive automated testing framework
- **Documentation**: All code must be documented (DoD v2.0 requirement)
### Quality Assurance (Sprint3 Process Quality Foundation)
```bash
# Sprint3 automated quality pipeline
npm run test # Automated test suite
./scripts/dod-check.sh # Definition of Done v2.0 validation
npm audit # Security vulnerability check
npm run lint # Code quality validation
```
### Release Process (Sprint3 Automated)
1. **Semantic Commits**: Automated version management via commit messages
2. **CI/CD Pipeline**: Automated testing across multiple platforms
3. **Quality Gates**: DoD v2.0 compliance before release
4. **Automated Publishing**: GitHub Actions handles npm publish
5. **Documentation**: Auto-generated release notes and documentation
## 📝 Changelog
See [CHANGELOG.md](CHANGELOG.md) for detailed version history and Sprint3 achievements.
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **Model Context Protocol Team** - For the innovative MCP framework
- **TypeScript Community** - For excellent tooling and type safety
- **Open Source Contributors** - For making this project possible
- **Sprint3 Quality Assurance** - For establishing enterprise-grade standards
---
## 🚀 Sprint3 Final Notes
**MCP LLM Generator v2 now includes enterprise-grade Process Quality Foundation:**
### 🎯 Production Ready Features
- ✅ **Zero-downtime operations** with comprehensive monitoring
- ✅ **24/7 support procedures** with emergency response plans
- ✅ **Automated quality assurance** with Definition of Done v2.0
- ✅ **Complete documentation suite** for all operational scenarios
- ✅ **CI/CD automation** with multi-platform validation
### 📈 Next Steps
1. **Deploy to production** with confidence using our operations manual
2. **Monitor system health** using provided health check scripts
3. **Scale operations** following our comprehensive procedures
4. **Contribute** using our established quality standards
**Made with ❤️ and Sprint3 Process Quality Foundation for the AI development community**
> **⭐ Star this repo** if you find Sprint3's Process Quality Foundation valuable! Your support helps us maintain enterprise-grade MCP standards.
