AGI-MCP: Advanced General Intelligence Model Context Protocol Server

A comprehensive Model Context Protocol (MCP) server implementing AGI-like capabilities through the GOTCHA Framework, ATLAS Process, Thinking Mechanism, Hook System, and Subagent Architecture with integrated database memory for persistent state management.

🌟 Features

🎯 GOTCHA Framework (6-Layer Architecture)

A sophisticated cognitive architecture for agentic systems:

Goals (G) - Define and manage objectives with priorities
Observations (O) - Perceive and record environmental state
Thoughts (T) - Reason and plan based on observations
Commands (C) - Select and execute actions systematically
Hypotheses (H) - Form and validate predictions
Assessments (A) - Evaluate performance and capture learnings

🗺️ ATLAS Process (5-Step Methodology)

Structured task execution methodology:

Analyze (A) - Understand task context and complexity
Task Breakdown (T) - Decompose into manageable subtasks
Learn (L) - Gather necessary knowledge and resources
Act (A) - Execute planned actions systematically
Synthesize (S) - Integrate results and extract insights

🧠 Thinking Mechanism

Intelligent reasoning and filtering layer:

Prompt Evaluation - Assesses relevance and safety of user inputs
Tool Use Validation - Evaluates appropriateness of tool execution
Completion Assessment - Determines when work is truly complete
Purpose-Based Filtering - Aligns all actions with agent purpose

🔗 Hook System

Claude Code-style lifecycle hooks for customization:

11 Hook Events - SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart/Stop, and more
Command & Prompt Hooks - Both shell command and LLM-based evaluation
Decision Control - Allow, deny, or modify operations dynamically
Context Injection - Add information at key lifecycle points

🤖 Subagent System

Specialized AI assistants for focused tasks:

4 Built-in Subagents - Explore, General-Purpose, Task-Executor, Code-Reviewer
Custom Subagents - Create project or user-level specialists
Isolated Contexts - Each subagent has its own memory and permissions
Tool Restrictions - Fine-grained control over subagent capabilities
Resumable Sessions - Continue previous subagent work

💾 Database Integration

Persistent memory as source of truth:

SQLite Database - All operations persisted
Session Tracking - Complete history and analytics
ATLAS History - Full execution traces
Query Optimization - Indexed for performance

🏗️ Memory Infrastructure

Automatic initialization and management:

Auto-Detection - Checks for existing infrastructure
Directory Creation - memory/logs and data structures
Schema Initialization - Database setup on first run
Logging System - Comprehensive session logs

📦 Installation

Standard Installation

# Clone the repository
git clone https://github.com/muah1987/AGI-MCP.git
cd AGI-MCP

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Docker Installation

# Option 1: Pull from Docker Hub (recommended)
docker pull muah1987/agi-mcp:latest

# Option 2: Build locally
docker build -t agi-mcp:latest .

# Option 3: Use docker-compose
docker-compose build

# Run the test script to validate the build
./test-docker.sh

Publishing to Docker Hub

Manual Publishing

# 1. Create .env file with your credentials
cp .env.example .env
# Edit .env and add your DOCKER_USERNAME and DOCKER_TOKEN

# 2. Build and push to Docker Hub
./push-docker.sh

Automated Publishing with GitHub Actions

The repository includes a GitHub Actions workflow that automatically builds and pushes Docker images to DockerHub on every push to the main branch or when a tag is created.

Setup:

Add the following secrets to your GitHub repository settings:
- DOCKER_LOGIN - Your DockerHub username
- DOCKER_PASSWORD - Your DockerHub password or access token
The workflow will automatically:
- Build the Docker image using the Dockerfile
- Tag it with latest and the version from package.json
- Push it to DockerHub under $DOCKER_LOGIN/agi-mcp (where $DOCKER_LOGIN is your DockerHub username)

Manual Trigger:

You can also trigger the workflow manually from the Actions tab in GitHub.

🚀 Quick Start

As MCP Server (Native)

Add to your MCP client configuration (e.g., Claude Desktop, Cline):

{
  "mcpServers": {
    "agi-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/AGI-MCP/dist/index.js"]
    }
  }
}

As MCP Server (Docker)

Using Docker for isolated deployment:

{
  "mcpServers": {
    "agi-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "muah1987/agi-mcp:latest"]
    }
  }
}

Or using locally built image:

{
  "mcpServers": {
    "agi-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "agi-mcp:latest"]
    }
  }
}

Direct Execution

# Native
npm start

# Docker
docker run -i agi-mcp:latest

# Docker Compose
docker-compose up

First Session

On first run, AGI-MCP automatically:

Creates memory/MEMORY.md documentation
Sets up memory/logs/ directory
Creates data/ directory
Initializes SQLite database
Loads all subagents
Configures hook system

🛠️ Available Tools

GOTCHA Framework (7 tools)

set_goal - Define system objectives
observe - Record environmental observations
think - Capture reasoning processes
execute_command - Execute and log commands
form_hypothesis - Create predictions
assess_performance - Evaluate and learn
process_goal_with_gotcha - Full cycle processing

ATLAS Process (2 tools)

execute_atlas_task - Run complete 5-step process
get_atlas_history - View task execution history

Memory Management (3 tools)

get_active_goals - List active objectives
get_memory - Query memory by layer
get_session_summary - Session overview

Subagent Management (3 tools)

execute_subagent - Delegate to specialist
resume_subagent - Continue previous work
list_subagents - View available subagents

📚 Documentation

Core Documentation

README.md - This file, project overview
CONTRIBUTING.md - Contribution guidelines
CODE_OF_CONDUCT.md - Community standards
SECURITY.md - Security policy and reporting
CHANGELOG.md - Version history
LICENSE - MIT License

Technical Documentation (docs/)

docs/ARCHITECTURE.md - System architecture and design
docs/ADVANCED.md - Thinking Mechanism, Hooks, and Subagents
docs/USAGE.md - Comprehensive usage guide with examples
docs/SKILLS.md - Skill system and orchestration
docs/QUICKREF.md - Quick reference for developers
docs/AGENTS.md - Subagent documentation
docs/GETTING_STARTED.md - Quickstart guide
docs/DEPLOYMENT.md - Deployment guide
docs/API.md - Complete API documentation
docs/MEMORY_SYSTEM.md - Memory architecture
docs/PROJECT_SUMMARY.md - Project statistics

🏗️ Architecture

AGI-MCP/
├── src/
│   ├── index.ts                 # Main MCP server
│   ├── database/
│   │   ├── memory-db.ts         # SQLite operations
│   │   └── infrastructure.ts     # Auto-initialization
│   ├── gotcha/
│   │   ├── framework.ts         # GOTCHA 6-layer system
│   │   └── thinking.ts          # Thinking mechanism
│   ├── atlas/
│   │   └── process.ts           # ATLAS 5-step process
│   ├── hooks/
│   │   └── hook-system.ts       # Lifecycle hooks
│   ├── subagents/
│   │   └── subagent-system.ts   # Subagent management
│   └── tools/
│       └── mcp-tools.ts         # MCP tool definitions
├── memory/                      # Memory system
│   ├── MEMORY.md               # Documentation
│   └── logs/                   # Session logs
├── data/                       # Database storage
│   └── agi-mcp.db             # SQLite database
└── .agi-mcp/                  # Configuration
    ├── hooks/                  # Hook scripts
    ├── subagents/             # Custom subagents
    └── hooks-config.json      # Hook configuration

💡 Examples

Execute ATLAS Task

await tools.handleToolCall('execute_atlas_task', {
  task_id: 'research-001',
  description: 'Research quantum computing applications'
});

Use Subagent

await tools.handleToolCall('execute_subagent', {
  subagent: 'code-reviewer',
  task: 'Review authentication module for security'
});

Configure Hook

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "execute_command",
      "hooks": [{
        "type": "command",
        "command": "./validate-command.sh"
      }]
    }]
  }
}

🧪 Testing

# Run all tests
npm test

# Build project
npm run build

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔒 Security

See SECURITY.md for security policies and reporting vulnerabilities.

📝 Changelog

See CHANGELOG.md for version history and changes.

🙏 Acknowledgments

Model Context Protocol by Anthropic
Inspired by AGI principles and cognitive architectures
Built with TypeScript and SQLite

📧 Support

Create an Issue
Read the Documentation
Check Discussions

AGI-MCP - Building towards Artificial General Intelligence through Model Context Protocol

AGI-MCP