# ContextX

> ContextX: Context-driven AI development framework powered by Claude Code. Transform documents into complete projects with intelligent agent workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-yzfly-contextx`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yzfly](https://agentstack.voostack.com/s/yzfly)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [yzfly](https://github.com/yzfly)
- **Source:** https://github.com/yzfly/ContextX

## Install

```sh
agentstack add mcp-yzfly-contextx
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ContextX

  
  
  

**From Documents to Code - Let AI Understand Your Complete Intent**

Context engineering framework based on Claude Code that intelligently analyzes project complexity and automatically selects the most suitable development workflow.

**Core Advantages:** One-Click Project Generation • Context-Aware • Zero-Config Startup

English | [简体中文](./README_CN.md)

## 📖 Project Overview

### What is this?
ContextX is a context engineering framework powered by Claude Code that automatically generates complete code projects from your documents and requirement descriptions.

### What problems does it solve?
- **Requirement Communication Difficulties**: AI struggles to understand complete context of complex projects
- **Low Development Efficiency**: Repetitive project setup and configuration work
- **Unstable Quality**: Lack of standardized AI-assisted development processes

### Use Cases
- 🚀 Rapid prototype development
- 📚 Document-based project implementation
- 🔄 Automated generation of repetitive projects
- 🧠 AI-assisted development of complex business logic

## ⚡ Quick Start

### Prerequisites
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) > 1.0.61
- Git

### 3-Step Setup

**Step 1: Get the Framework**
```bash
git clone https://github.com/yzfly/ContextX.git
cd ContextX
```

**Step 2: Prepare Project Context**
```bash
# Prepare your project materials in the .contextx directory
.contextx/
├── TASK_PROMPT.md          # Project requirements description
├── data/                   # Related documentation
└── examples/               # Reference code (optional)
```

**Step 3: Generate Project**
```bash
# Claude Code will automatically analyze complexity and choose the right workflow
claude "/create Your project requirements description"
```

### First Project Example

Create a simple Todo application:

```bash
# 1. Prepare requirements description
echo "Create a React Todo app with add, delete, and mark complete functionality" > .contextx/TASK_PROMPT.md

# 2. Run generation command
claude "/create React-based Todo application"

# 3. View generated results
ls -la  # Check generated project files
```

## 💡 Core Concepts

### Context-Driven Development
AI programming paradigm driven by Markdown documents, where documents serve as the project's knowledge base and context source.

**Philosophy:** *We used to program with code, now we program with documents*

### Intelligent Complexity Analysis
System automatically analyzes task complexity and selects the most suitable agent workflow:

```
Simple Tasks  →  Builder Agent (Direct Build)
Medium Tasks  →  Designer → Builder (Design then Build)  
Complex Tasks →  Learner → Designer → Builder (Learn-Design-Build)
```

### Agent Collaboration Model

| Agent | Responsibility | Trigger Condition |
|-------|----------------|-------------------|
| **Learner** | Learn and organize external docs, analyze technical specs | Need to understand complex docs or new technologies |
| **Designer** | Requirements analysis, architecture design, solution planning | Need system design and technology selection |
| **Builder** | Code implementation, documentation, deployment config | Required for all projects |

## 📚 Usage Guide

### Project Preparation

#### 1. Context Directory Structure
```
.contextx/
├── TASK_PROMPT.md          # [Required] Project requirements description
├── data/                   # [Optional] Related documentation
│   ├── api_docs.md         # API documentation
│   ├── business_rules.md   # Business rules
│   └── web_docs.md         # Web links (auto-fetch)
├── examples/               # [Optional] Reference code
│   ├── template.js         # Code templates
│   └── reference.py        # Reference implementations
├── knowledge/              # [Auto-generated] Structured knowledge base
└── PRC.md                  # [Auto-generated] Project requirements document
```

#### 2. TASK_PROMPT.md Writing Guide

**Basic Template:**
```markdown
# Project Requirements

## Project Overview
[One-sentence description of project goal]

## Functional Requirements
- [ ] Feature 1
- [ ] Feature 2

## Technical Requirements
- Programming Language:
- Framework Choice:
- Database: (if needed)

## Special Requirements
[Any special implementation requirements or constraints]
```

**Advanced Template (Complex Projects):**
```markdown
# Project Requirements

## Background
[Project background and business value]

## User Stories
- As a [user role], I want [feature description], so that [business value]

## Functional Requirements
### Core Features
- [ ] Detailed feature description 1
- [ ] Detailed feature description 2

### Extended Features
- [ ] Optional feature 1

## Non-Functional Requirements
- Performance Requirements:
- Security Requirements:
- Maintainability:

## Technical Architecture
- Frontend Tech Stack:
- Backend Tech Stack:
- Data Storage:
- Deployment Method:

## Constraints
[Technical constraints, time constraints, etc.]
```

### Configuration Instructions

#### Tool Integration (Optional)
To enhance network search capabilities, install:

```bash
# 1. Install context-mcp-server
claude mcp add context-mcp-server -e CONTEXT_DIR=$(pwd)/context/knowledge -- uvx context-mcp-server

# 2. Verify installation
claude mcp list
```

#### Web Document Retrieval
Add web links to fetch in `data/web_docs.md`:

```markdown
# Web Document Links

## API Documentation
- https://docs.example.com/api/v1
- https://developer.example.com/guides

## Technical References
- https://framework.example.com/docs
```

### Best Practices

#### ✅ Recommended Practices
- Be specific and clear in requirement descriptions, avoid vague statements
- Provide relevant technical documentation and API specifications
- Include specific functional examples or use cases
- Clearly specify tech stack and architecture preferences

#### ❌ Things to Avoid
- Requirements that are too simple or too complex
- Lack of key technical constraint explanations
- Insufficient contextual information
- Frequent requirement changes causing context inconsistency

## 🏗️ Architecture Design

### System Architecture Diagram

```
                    ┌───────────────────────────────┐
                    │        /create Entry          │
                    │   Intelligent Complexity      │
                    │        Analysis               │
                    └──────────────┬────────────────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
            ▼                      ▼                      ▼
    ┌───────────────┐      ┌───────────────┐      ┌───────────────┐
    │ Simple Tasks  │      │ Medium Tasks  │      │ Complex Tasks │
    │               │      │               │      │               │
    │   Builder     │      │  Designer     │      │   Learner     │
    │               │      │     ↓         │      │     ↓         │
    │               │      │  Builder      │      │  Designer     │
    │               │      │               │      │     ↓         │
    │               │      │               │      │  Builder      │
    └───────┬───────┘      └───────┬───────┘      └───────┬───────┘
            │                      │                      │
            └──────────────────────┼──────────────────────┘
                                   │
                                   ▼
                    ┌───────────────────────────────┐
                    │    Complete Project Delivery  │
                    │ • Fully functional source code│
                    │ • Detailed project docs       │
                    │ • Deployment configuration    │
                    │ • Usage instructions          │
                    └───────────────────────────────┘
```

### Detailed Agent Design

#### Learner Agent
**Responsibility:** Knowledge organization and learning
- Parse external documents and technical specifications
- Process web resources and API documentation
- Generate structured knowledge base
- Provide accurate technical background for subsequent agents

**Input:** Raw documents, web links, technical materials
**Output:** Structured documents in `.contextx/knowledge/` directory

#### Designer Agent  
**Responsibility:** Requirements analysis and architecture design
- Analyze project requirements and technical specifications
- Design system architecture and module structure
- Formulate technology selection and implementation plans
- Generate detailed project requirements document (PRC.md)

**Input:** Task requirements, knowledge base, technical constraints
**Output:** `.contextx/PRC.md` project requirements document

#### Builder Agent
**Responsibility:** Code implementation and project delivery
- Write complete code based on requirements and design
- Implement all functional modules and interfaces
- Generate configuration files and deployment scripts
- Write project documentation and usage instructions

**Input:** Project requirements document, design plan, code examples
**Output:** Complete project code and documentation

### Decision Flow

```
User Input Requirements
    │
    ▼
┌─────────────────┐
│ Requirements    │ ── Generate/optimize TASK_PROMPT.md
│ Preprocessing   │
└─────┬───────────┘
      │
      ▼
┌─────────────────┐
│ Context Resource│ ── Check data/, examples/ directories
│ Scanning        │
└─────┬───────────┘
      │
      ▼
┌─────────────────┐     ┌─────────────────┐
│ Intelligent     │ ──→ │ Simple: Direct  │
│ Complexity      │     │ Build           │
│ Assessment      │     └─────────────────┘
│                 │     ┌─────────────────┐
│ Assessment      │ ──→ │ Medium: Design  │
│ Dimensions:     │     │ + Build         │
│ • Requirement   │     └─────────────────┘
│   Clarity       │     ┌─────────────────┐
│ • Technical     │ ──→ │ Complex: Full   │
│   Difficulty    │     │ Process         │
│ • External      │     └─────────────────┘
│   Dependencies  │
│ • Material      │
│   Completeness  │
└─────────────────┘
```

## ⚙️ Advanced Configuration

### Custom Agents

Create custom agents in the `.claude/agents/` directory:

```markdown
# custom_agent.md

## Role Definition
[Description of agent's responsibilities and capabilities]

## Workflow
[Detailed work steps]

## Input/Output
- Input: [Expected input format]
- Output: [Output format and content]
```

### Extension Commands

Add custom commands in the `.claude/commands/` directory:

```markdown
# custom_command.md

## Command Description
/custom - Custom functionality description

## Usage
[Specific usage of the command]

## Parameter Description
[Detailed parameter explanations]
```

### Configuration File

Edit `.claude/settings.local.json` for personalized configuration:

```json
{
  "default_model": "claude-3-5-sonnet-20241022",
  "context_window": 200000,
  "temperature": 0.7,
  "custom_settings": {
    "preferred_language": "en-US",
    "code_style": "standard",
    "documentation_level": "detailed"
  }
}
```

## 📖 Usage Examples

### Example 1: Web Application Development

```bash
# 1. Prepare requirements
cat > .contextx/TASK_PROMPT.md  .contextx/data/api_docs.md  .contextx/TASK_PROMPT.md 

**If this project helps you, please give it a ⭐️**

[](https://www.star-history.com/#yzfly/ContextX&Date)

Made with ❤️ by [yzfly](https://github.com/yzfly)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yzfly](https://github.com/yzfly)
- **Source:** [yzfly/ContextX](https://github.com/yzfly/ContextX)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yzfly-contextx
- Seller: https://agentstack.voostack.com/s/yzfly
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.