CODITECT Standard: Tools

Version: 1.0.0 Status: Approved Last Updated: February 7, 2026 Authority: ADR-161 Component Quality Assurance Framework

Executive Summary

This standard defines the authoritative specification for tools in the CODITECT framework. Tools are standalone utility projects that provide capabilities beyond what agents, skills, and scripts offer — including MCP (Model Context Protocol) servers, web applications, CLI utilities, and developer tools.

Key Requirements:

Tools MUST be organized as directories under tools/ with a README.md
Tools MUST document features/capabilities, architecture, setup, and troubleshooting
MCP tools MUST document their tool functions and configuration for settings.json
Tools SHOULD include usage examples with expected output
Tools MUST list all dependencies explicitly
Tools SHOULD include architecture documentation (data flows, component interactions)

Compliance Target: All CODITECT tools must achieve Grade B (80%) or higher within 30 days of this standard publication.

Tool Categories
Directory Structure
README Requirements
MCP Server Standards
Web Application Standards
CLI Tool Standards
Quality Grading
Templates
Troubleshooting
References

Tool Categories

4 Tool Categories

Category	Description	Examples
MCP Server	Model Context Protocol servers providing tools to Claude Code	mcp-call-graph, mcp-context-graph, mcp-backup
Web Application	Browser-based UI tools	component-viewer, bi-dashboard, trajectory-visualizer
CLI Utility	Command-line developer tools	cloud-sync, context-watcher
Processing Pipeline	Data transformation utilities	transcript-normalization

Current Tool Inventory (15 tools)

Tool	Category	Description
bi-dashboard	Web App	Business intelligence dashboard
cloud-sync	CLI	Cloud storage synchronization
component-viewer	Web App	Visual component browser
context-watcher	CLI	Real-time context monitoring
mcp-backup	MCP	Context database backup/restore
mcp-call-graph	MCP	Code call graph indexing and querying
mcp-context-graph	MCP	Knowledge graph navigation
mcp-cross-llm-bridge	MCP	Multi-LLM provider routing
mcp-git-status	MCP	Git repository status
mcp-impact-analysis	MCP	Change impact analysis
mcp-semantic-search	MCP	Semantic code search
mcp-skill-server	MCP	Skill content serving
mcp-unified-gateway	MCP	Unified MCP gateway
trajectory-visualizer	Web App	Agent trajectory visualization
transcript-normalization	Pipeline	Transcript processing

Directory Structure

Required Structure

tools/<tool-name>/
├── README.md              # REQUIRED: Main documentation
├── package.json           # For Node.js tools (name, version, dependencies)
├── Cargo.toml             # For Rust tools
├── requirements.txt       # For Python tools
├── src/                   # Source code
│   └── index.ts           # Entry point (TypeScript MCP servers)
├── Dockerfile             # Optional: Container support
└── .env.example           # Optional: Environment variable template

Naming Conventions

Element	Convention	Example
Directory name	lowercase-kebab-case	`mcp-call-graph`
MCP prefix	`mcp-` for MCP servers	`mcp-backup`, `mcp-semantic-search`
README	`README.md` (uppercase)	Always at tool root
Source entry	Language-specific	`src/index.ts`, `src/main.rs`, `main.py`

README Requirements

Required Sections

Every tool README.md MUST include:

1. Title and Description (Header)

# Tool Name

Brief one-line description of what the tool does.

2. Features / Capabilities

## Features

- **Feature 1:** Description of capability
- **Feature 2:** Description of capability
- **Feature 3:** Description of capability

For MCP servers, list all available tools:

## MCP Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `tool_name` | What it does | `param1` (required), `param2` (optional) |

3. Architecture

## Architecture

Brief description of how the tool works internally.

### Data Flow

Input → Processing → Output

### Component Interactions

Describe how this tool interacts with other CODITECT components.

4. Setup / Installation

## Setup

### Prerequisites

- Node.js >= 18 (or Python >= 3.10, Rust >= 1.70)
- Required system dependencies

### Installation

```bash
cd tools/<tool-name>
npm install  # or pip install -r requirements.txt

Configuration

For MCP servers, add to .claude/settings.json:

{
  "mcpServers": {
    "tool-name": {
      "command": "node",
      "args": ["tools/tool-name/src/index.ts"]
    }
  }
}

#### 5. Usage Examples

```markdown
## Usage

### Example 1: Basic Usage

```bash
# Command or invocation
tool-name --option value

Expected output:

Output here

Example 2: Advanced Usage

tool-name --advanced-option

#### 6. Troubleshooting

```markdown
## Troubleshooting

### Common Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| Tool not found | Not in PATH | Run `npm install` or check `settings.json` |
| Connection refused | Server not running | Start with `npm start` |

### Debug Mode

```bash
DEBUG=true tool-name --verbose

### Optional Sections

- **API Reference** — for tools exposing HTTP/WebSocket APIs
- **Development** — for contributor setup instructions
- **Testing** — for running tool-specific tests
- **Changelog** — version history
- **License** — if different from framework license

---

## MCP Server Standards

### Configuration Format

MCP servers MUST document their `settings.json` configuration:

```json
{
  "mcpServers": {
    "<server-name>": {
      "command": "node",
      "args": ["path/to/src/index.ts"],
      "env": {
        "OPTIONAL_VAR": "value"
      }
    }
  }
}

Tool Function Documentation

Each MCP tool function MUST document:

Name — tool function name (snake_case)
Description — what it does (shown to Claude)
Parameters — name, type, required/optional, description
Return value — shape of successful response
Error handling — what errors can occur

MCP Best Practices

Use TypeScript with strict mode for type safety
Implement proper error responses (not just throwing)
Log tool invocations for debugging
Support graceful shutdown
Document environment variables in .env.example

Web Application Standards

Requirements

MUST serve on a configurable port (default documented)
MUST include start/stop instructions
SHOULD support hot reload for development
MUST document browser compatibility requirements

Technology Preferences

Stack	Use Case
Next.js / React	Complex interactive UIs
Vanilla HTML/JS	Simple viewers, dashboards
Svelte	Lightweight reactive UIs

CLI Tool Standards

Requirements

MUST support --help flag
MUST support --version flag
MUST use non-zero exit codes on failure
SHOULD support --verbose for debug output
SHOULD support --dry-run for destructive operations

Quality Grading

Grading Categories

Category	Weight	Description
A. Feature Documentation	20%	Capabilities listed, MCP tools documented
B. Usage Examples	25%	2+ examples, config examples, integration patterns
C. Architecture	20%	System design, data flows documented
D. Setup & Installation	20%	Installation steps, dependencies listed
E. Troubleshooting	15%	Common issues, debug resources

Grading Checks

A. Feature Documentation (20%)

A1 (10pts): Capabilities/features section present with 2+ items
A2 (10pts): MCP tools documented (if applicable) or N/A for non-MCP tools

B. Usage Examples (25%)

B1 (10pts): At least 2 usage examples with commands/code
B2 (8pts): Configuration examples shown (settings.json, env vars)
B3 (7pts): Integration patterns with other CODITECT components demonstrated

C. Architecture (20%)

C1 (10pts): System design / how-it-works section present
C2 (10pts): Data flows or component interaction diagrams

D. Setup & Installation (20%)

D1 (10pts): Installation steps documented (prerequisites, commands)
D2 (10pts): Dependencies explicitly listed (package.json, requirements.txt, or in README)

E. Troubleshooting (15%)

E1 (8pts): Common issues section with problem/solution pairs
E2 (7pts): Debug approach or support resources documented

Grade Scale

Grade	Score	Meaning
A	90-100%	Production-ready, exemplary documentation
B	80-89%	Production-ready, minor documentation gaps
C	70-79%	Functional, moderate documentation improvements needed
D	60-69%	Significant documentation gaps
F	<60%	Does not meet minimum documentation standards

Grader Script

python3 scripts/qa/grade-tools.py [tool-dir] [--json output.json] [--verbose]

Templates

Minimal MCP Server README

# mcp-example

One-line description of MCP server purpose.

## Features

- **Feature 1:** Description
- **Feature 2:** Description

## MCP Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `example_tool` | What it does | `input` (required) |

## Setup

```bash
cd tools/mcp-example
npm install

Add to .claude/settings.json:

{
  "mcpServers": {
    "mcp-example": {
      "command": "node",
      "args": ["tools/mcp-example/src/index.ts"]
    }
  }
}

Usage

# Tool is available to Claude after configuration
# Claude can call: mcp__mcp_example__example_tool

Architecture

Brief description of internal design.

Troubleshooting

Issue	Solution
Server won't start	Check `npm install` completed

### Standard CLI Tool README

```markdown
# tool-name

One-line description.

## Features

- Feature 1
- Feature 2

## Setup

### Prerequisites
- Python 3.10+

### Installation
```bash
pip install -r requirements.txt

Usage

Basic

python3 tools/tool-name/main.py --input file.txt

Advanced

python3 tools/tool-name/main.py --input file.txt --verbose --output result.json

Architecture

How it works internally.

Dependencies

dependency-1: purpose
dependency-2: purpose

Troubleshooting

Issue	Cause	Solution
Import error	Missing dep	`pip install -r requirements.txt`

---

## Troubleshooting

### Standard Validation Issues

| Issue | Fix |
|-------|-----|
| Missing README.md | Create README.md following template above |
| No features section | Add `## Features` with 2+ bullet points |
| No architecture docs | Add `## Architecture` with system description |
| MCP tools undocumented | Add `## MCP Tools` table with all tool functions |
| No troubleshooting | Add `## Troubleshooting` with common issues table |

---

## References

- **ADR-161:** Component Quality Assurance Framework
- **Grader:** `scripts/qa/grade-tools.py`
- **Shared Library:** `scripts/qa/qa_common.py`
- **Skill:** `skills/qa-grading-framework/SKILL.md`
- **MCP Specification:** [Model Context Protocol](https://modelcontextprotocol.io/)

---

**Standard:** CODITECT-STANDARD-TOOLS v1.0.0
**Author:** AZ1.AI INC

Executive Summary​

Table of Contents​

Tool Categories​

4 Tool Categories​

Current Tool Inventory (15 tools)​

Directory Structure​

Required Structure​

Naming Conventions​

README Requirements​

Required Sections​

1. Title and Description (Header)​

2. Features / Capabilities​

3. Architecture​

4. Setup / Installation​

Configuration​

Example 2: Advanced Usage​

Tool Function Documentation​

MCP Best Practices​

Web Application Standards​

Requirements​

Technology Preferences​

CLI Tool Standards​

Requirements​

Quality Grading​

Grading Categories​

Grading Checks​

A. Feature Documentation (20%)​

B. Usage Examples (25%)​

C. Architecture (20%)​

D. Setup & Installation (20%)​

E. Troubleshooting (15%)​

Grade Scale​

Grader Script​

Templates​

Minimal MCP Server README​

Usage​

Architecture​

Troubleshooting​

Usage​

Basic​

Advanced​

Architecture​

Dependencies​

Troubleshooting​

Executive Summary

Table of Contents

Tool Categories

4 Tool Categories

Current Tool Inventory (15 tools)

Directory Structure

Required Structure

Naming Conventions

README Requirements

Required Sections

1. Title and Description (Header)

2. Features / Capabilities

3. Architecture

4. Setup / Installation

Configuration

Example 2: Advanced Usage

Tool Function Documentation

MCP Best Practices

Web Application Standards

Requirements

Technology Preferences

CLI Tool Standards

Requirements

Quality Grading

Grading Categories

Grading Checks

A. Feature Documentation (20%)

B. Usage Examples (25%)

C. Architecture (20%)

D. Setup & Installation (20%)

E. Troubleshooting (15%)

Grade Scale

Grader Script

Templates

Minimal MCP Server README

Usage

Architecture

Troubleshooting

Usage

Basic

Advanced

Architecture

Dependencies

Troubleshooting