Ai Cognitive Nexus MCP

🚀 AI Cognitive Nexus

A professional and dynamically configurable MCP for AI team collaboration and orchestration. It allows you to create, manage, and direct hierarchical teams composed of multiple AI agents through simple instructions to tackle complex and multi - stage tasks.

✨ Features

• 🤖 Dynamic Team Composition: Create, update, and delete AI teams in real - time. Team members can be individual AI agents or even other teams, enabling infinite hierarchical collaboration.
• 🧠 Context Injection: Provide precise role - playing instructions and professional domain knowledge for AI teams to perform tasks through the Persona and Product systems.
• 🔗 Hierarchical Team Dependencies: The system automatically handles complex team dependencies (e.g., Team A is a member of Team B). It uses topological sorting to ensure the correct initialization order and can detect and prevent circular dependencies.
• 💾 Persistent Session State: The built - in session manager can track and record multi - round conversation histories, allowing AI teams to have long - term memory and handle continuous tasks.
• 🔌 Pluggable Large Models: Support seamless switching between different large language model providers (e.g., DeepSeek, OpenAILike services) via environment variables to flexibly meet different cost and performance requirements.
• 🛠️ Extensible Agent Tools: Configure a dedicated toolset (e.g., ThinkingTools, ExaTools) for each AI agent, endowing it with professional skills beyond language capabilities.
• 🤝 Native MCP Protocol: Built on the Model Context Protocol, it can be seamlessly integrated with any AI assistant that supports MCP (e.g., OpenAI Assistants, Coze, Dify, Chatwise).

🚀 Core Concepts

The powerful capabilities of Cognitive Nexus stem from the combination and collaboration of the following core concepts:

Workflow: When a task starts, you can specify a Team as the executor and equip it with a specific Persona and Product as context to precisely guide the team to complete the task.

📦 Installation

1. Environment Requirements

• Python 3.10+
• Python package management tools such as pip or uv
• AI clients that support MCP (e.g., Coze, Dify, or other compatible Agents)

2. Install Dependencies

# 1. Clone the project
git clone https://github.com/SimonUTD/ai-cognitive-nexus-mcp.git
cd ai-cognitive-nexus-mcp

# 2. (Recommended) Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # on Windows, use `.venv\Scripts\activate`

# 3. Install dependencies
pip install -r requirements.txt

3. Configure the .env File

This is the preferred way to configure the model provider and API Key.

# 1. Copy the environment variable template
cp .env.example .env

# 2. Edit the .env file and fill in your configuration information
# LLM_PROVIDER: Set the default model service provider ("deepseek" or "openailike")
LLM_PROVIDER="deepseek"

# --- OpenAILike service provider configuration ---
# If you use OpenAI-compatible interfaces such as ZhipuAI, Moonshot, Groq, etc., configure the following three items
OpenAILike_API_KEY="your_api_key_here"
OpenAILike_BASE_URL="https://api.example.com/v1"
OpenAILike_MODEL_ID="glm-4" # Model for team coordination
OpenAILike_AGENT_MODEL_ID="glm-4" # Model for individual Agents

# EXA search configuration
EXA_API_KEY="your_exa_key_here" # API Key for EXA tools

4. Start the Server

You can start the MCP server through standard input and output (stdio) by directly running main.py.

python main.py

You can also configure this command in an MCP - supported client (e.g., Chatwise) for automatic startup.

📚 Documentation (MCP Tools)

Cognitive Nexus exposes a series of tools to AI assistants for managing and running AI teams.

Session Management

• start_session(initial_context: str): Create a new session to track subsequent interaction histories.

Persona Management

• create_persona(persona_key: str, data: dict): Create a new persona.
• list_personas(): List all available personas.
• get_persona(persona_key: str): Get detailed information about a specified persona.
• update_persona(persona_key: str, data: dict): Update an existing persona.
• delete_persona(persona_key: str): Delete a persona.

Product Management

• create_product(product_key: str, data: dict): Create a new product and its knowledge base.
• list_products(): List all products.
• get_product(product_key: str): Get product details and the knowledge base.
• update_product(product_key: str, data: dict): Update product information.
• delete_product(product_key: str): Delete a product.

Agent Management

• create_agent(agent_key: str, data: dict): Create an independent AI agent.
• list_agents(): List all agents.
• get_agent(agent_key: str): Get agent configuration.
• update_agent(agent_key: str, data: dict): Update agent configuration (all teams will be automatically reloaded).
• delete_agent(agent_key: str): Delete an agent.

Team Management

• create_team(team_key: str, data: dict): Create a new team.
• list_teams(): List all teams and their statuses (activated/configuration error).
• get_team_config(team_key: str): Get the original configuration of a team.
• update_team(team_key: str, data: dict): Update team configuration (will automatically attempt to reload).
• delete_team(team_key: str): Delete a team.

Core Execution Unit

• run_ai_team(team_name: str, prompt: str, session_id: str, persona_key: str, product_key: str) This is the core function of the framework, used to direct a team to perform tasks.
  • team_name (Required): The key of the team to run.
  • prompt (Required): The core instruction for this task.
  • session_id (Optional): The associated session ID for loading history and saving results.
  • persona_key (Optional): The key of the persona that the AI needs to play in this task.
  • product_key (Optional): The key of the product associated with this task for loading a specific knowledge base.

❓ Frequently Asked Questions (FAQ)

Q: How can I create a "Product Manager Agent" and a "R & D Team" and let them collaborate?

A: It's very simple, just follow three steps:

1. Create Agents: Call create_agent to create a product_manager agent, and then create two R & D agents developer_a and developer_b. Describe their responsibilities in detail in description and instructions.
2. Create a Team: Call create_team to create a dev_team with a members list of ["developer_a", "developer_b"].
3. Run: Call run_ai_team to let the product_manager agent directly perform the task, or create a higher - level project_team with product_manager and dev_team as its members, and then run project_team.

Q: What will happen if I create a team with circular dependencies (e.g., Team A contains Team B, and Team B contains Team A)?

A: The system will automatically detect it. When you call create_team or update_team, if the new configuration introduces circular dependencies, the operation will fail and return an error message. At the same time, your changes will be automatically rolled back to ensure that the system is always in an available state.

Q: How can I switch the AI model I'm using, for example, from Zhipu's GLM - 4 to Moonshot?

A: Just modify the .env file:

1. Set LLM_PROVIDER="openailike".
2. Set OpenAILike_API_KEY to your Moonshot API Key.
3. Set OpenAILike_BASE_URL to Moonshot's service address (https://api.moonshot.cn/v1).
4. Set OpenAILike_MODEL_ID to the model ID you want to use (e.g., moonshot-v1-8k).
5. Set EXA_API_KEY to your EXA API Key.
6. Restart the MCP server for the changes to take effect.