JCode v3.0 - MCP-Based Agent Governance System

JCode is a 6-step governance workflow system for AI coding assistants, exposed via the Model Context Protocol (MCP). It brings structure, accountability, and quality control to AI-generated code.

Features • Quick Start • Documentation • Installation

---

🎯 What is JCode?

JCode implements a complete governance layer that ensures AI-generated code meets quality standards through a structured 6-step workflow:

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│   Analyst   │ → │   Planner   │ → │ Implementer │
│  (司马迁)   │   │   (商鞅)    │   │   (鲁班)    │
└─────────────┘   └─────────────┘   └─────────────┘
                                              ↓
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  Conductor  │ ← │    Tester   │ ← │   Reviewer  │
│  (韩非子)   │   │   (张衡)    │   │   (包拯)    │
└─────────────┘   └─────────────┘   └─────────────┘

Each step validates the previous, ensuring only high-quality code reaches production.

---

✨ Features

6 Specialized Agents

Agent	Role	Output
@jcode-analyst	Problem analysis & risk assessment	Analysis + Verifiability
@jcode-planner	Task decomposition & planning	Verifiable task list
@jcode-implementer	Code implementation	Code changes
@jcode-reviewer	Code review	APPROVED / REJECTED
@jcode-tester	Test verification	PASSED / FAILED
@jcode-conductor	Final arbitration	DELIVER / ITERATE / STOP

MCP Protocol Integration

• Standard Protocol: Implements Model Context Protocol (JSON-RPC 2.0)
• Tool Discovery: Auto-discoverable by MCP clients
• Stateless Design: Each invocation is independent
• Multi-Client Support: Works with OpenCode, VSCode, Claude Desktop, etc.

Auto-Start Options

• ✅ VSCode auto-start on project open
• ✅ System service (systemd/launchd)
• ✅ Docker container
• ✅ PM2 process management

---

🚀 Quick Start

1. Installation

git clone https://github.com/jabing/JCode.git
cd JCode
pip install -r requirements.txt

2. Configure OpenCode (or your MCP client)

Edit ~/.config/opencode/opencode.json:

{
  "mcp": {
    "jcode": {
      "type": "local",
      "command": ["python", "-m", "jcode_mcp.server", "--port", "8080"],
      "env": {"PYTHONPATH": "/path/to/jcode"},
      "enabled": true
    }
  }
}

3. Use JCode

In your MCP client:

@jcode 实现一个用户登录功能

Or use individual agents:

@jcode-analyst 分析这个需求的风险
@jcode-reviewer 检查这段代码
@jcode-tester 运行测试

---

📚 Documentation

Core Documentation

• 📖 Agent System Overview - Architecture & 6-agent workflow
• 🔧 Installation Guide - Detailed setup instructions
• ⚙️ VSCode Integration - VSCode setup & configuration
• 🚀 Auto-Start Guide - 5 methods to auto-start server
• 🛠️ Troubleshooting - Common issues & solutions

Governance Framework

• 📜 Agent Constitution - Core principles & constraints
• 🏛️ Governance Documentation - Complete governance framework
• 📋 Output Format Guidelines

API Reference

• 💻 MCP Server API - FastAPI-based MCP server
• 🔌 SKILL Registration - OpenCode SKILL format

---

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                  MCP Client                          │
│         (OpenCode / VSCode / Claude)                 │
└────────────────────┬────────────────────────────────┘
                     │ JSON-RPC 2.0
                     ▼
┌─────────────────────────────────────────────────────┐
│              JCode MCP Server                        │
│  ┌──────────┬──────────┬──────────┬───────────────┐  │
│  │ /health  │  /mcp    │ /docs    │   /openapi    │  │
│  └──────────┴──────────┴──────────┴───────────────┘  │
│                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐  │
│  │  analyze │ │   plan   │ │ implement│ │ review │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────┘  │
│  ┌──────────┐ ┌──────────┐                          │
│  │   test   │ │ conductor│                          │
│  └──────────┘ └──────────┘                          │
└─────────────────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│               Core Agents                            │
│   Analyst / Planner / Implementer / Reviewer /      │
│   Tester / Conductor                                │
└─────────────────────────────────────────────────────┘

---

🎨 Agent Personalities

Each JCode agent has a historical Chinese personality anchor that constrains its behavior:

Agent	Personality	Constraint
Analyst	司马迁 (Sima Qian)	Records facts only, no judgment
Planner	商鞅 (Shang Yang)	Creates laws, doesn't execute
Implementer	鲁班 (Lu Ban)	Follows blueprint exactly
Reviewer	包拯 (Bao Zheng)	Binary verdict only, no suggestions
Tester	张衡 (Zhang Heng)	Provides evidence, no speculation
Conductor	韩非子 (Han Feizi)	Final arbiter, no analysis

---

🧪 Testing

# Run all tests
pytest tests/ -v

# Run integration tests
pytest tests/integration/test_mcp_server.py -v

# Run with coverage
pytest tests/ --cov=jcode_mcp --cov-report=html

---

📦 Project Structure

jcode/
├── jcode_mcp/              # MCP Server implementation
│   ├── server.py           # FastAPI + JSON-RPC 2.0
│   ├── jcode_server.py     # Tool definitions
│   └── __init__.py
├── core/agents/            # 6 Agent implementations
│   ├── analyst.py
│   ├── planner.py
│   ├── implementer.py
│   ├── reviewer.py
│   ├── tester.py
│   └── conductor.py
├── config/agents/          # OpenCode Agent configs
│   ├── jcode.md            # Primary orchestrator
│   ├── jcode-analyst.md
│   ├── jcode-planner.md
│   ├── jcode-implementer.md
│   ├── jcode-reviewer.md
│   ├── jcode-tester.md
│   └── jcode-conductor.md
├── skills/jcode-mcp/       # OpenCode SKILL registration
│   └── SKILL.md
├── docs/                   # Documentation
│   ├── AUTO_START_GUIDE.md
│   ├── VSCODE_INTEGRATION.md
│   └── TROUBLESHOOTING.md
├── governance/             # Governance framework
│   ├── AGENT_CONSTITUTION.md
│   └── ...
└── tests/                  # Test suite
    └── integration/

---

🛣️ Roadmap

• MCP Server implementation
• 6 Agent tools exposed via MCP
• VSCode integration
• Auto-start configuration
• Web dashboard for workflow monitoring
• Multi-project support
• Custom agent plugins
• Enterprise SSO integration

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Development Setup

# Install dev dependencies
pip install -r requirements.txt

# Install pre-commit hooks
pre-commit install

# Run linting
ruff check .
black --check .

# Run tests
pytest

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

• Model Context Protocol - For the standardized tool protocol
• OpenCode - For the AI coding assistant framework
• FastAPI - For the high-performance web framework

---

📞 Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions

---

JCode: Governance as a Tool
让AI不只是写代码，而是写好代码