How do I use AGI-MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AGI-MCP Use the ATLAS process to break down the task of building a secure login system." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

AGI-MCP: Advanced General Intelligence Model Context Protocol Server

License: MIT TypeScript Node.js

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

# 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

🚀 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