AGI-MCP Server

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:

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

🗺️ ATLAS Process (5-Step Methodology)

Structured task execution methodology:

1. Analyze (A) - Understand task context and complexity
2. Task Breakdown (T) - Decompose into manageable subtasks
3. Learn (L) - Gather necessary knowledge and resources
4. Act (A) - Execute planned actions systematically
5. 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:

1. Add the following secrets to your GitHub repository settings:

   • DOCKER_LOGIN - Your DockerHub username
   • DOCKER_PASSWORD - Your DockerHub password or access token

2. 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":