Metadata-Version: 2.4
Name: aidocs-mcp
Version: 2.2.0b2
Summary: Portable AI coding-agent toolkit — MCP server with indexed code retrieval, session management, and persistent memory
Author-email: CodeNexus <hello@codenexus.cloud>
License: Apache-2.0
Project-URL: Homepage, https://codenexus.cloud
Project-URL: Repository, https://github.com/cristian1991/AIDOCS
Project-URL: Issues, https://github.com/cristian1991/AIDOCS/issues
Project-URL: Documentation, https://github.com/cristian1991/AIDOCS#readme
Keywords: ai,mcp,coding-agent,memory,session,code-index,claude,opencode
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Provides-Extra: ast
Requires-Dist: tree-sitter>=0.23.0; extra == "ast"
Requires-Dist: tree-sitter-javascript>=0.23.0; extra == "ast"
Requires-Dist: tree-sitter-typescript>=0.23.0; extra == "ast"

# AIDOCS MCP

**v2.2.0b** — The orchestration layer for AI coding agents — persistent memory, conductor, dashboard, and multi-agent workflows.

## What's New in 2.1.0b

- **Agent-agnostic orchestration** — `AgentOrchestrator` decouples gate logic from Claude Code; single `check_tool()` entry point
- **Heuristic judge** — 30+ rules with config-driven `[[policies.dangerous]]` for argument-level risk assessment
- **Output guard** — post-execution credential/injection scanning with auto-redaction
- **Metrics** — Prometheus-compatible counters (tokens, tool calls, guard stats)
- **Circuit breakers** — per-server failure tracking with exponential backoff
- **Edit history/rollback** — diff-based undo with SQLite storage
- **SQLite config store** — replaces TOML for runtime settings; TOML for static definitions only
- **RBAC** — users, roles (admin/operator/viewer), 15 permissions
- **Code runner** — structured bash replacements (`code_build`, `code_test`, `code_run`)
- **Tool policies** — admin allow/deny glob patterns
- **MCP registry** — official registry browser with search and install commands
- **Skill scanner** — content/supply-chain/capability/vulnerability risk assessment
- **Context compaction** — budget tracking + journal pruning + token reset on compaction
- **Deferred tool loading** — 50 eager tools visible, 70+ discovered via ToolSearch keywords
- **PostCompact hook** — resets token counters when host compacts context
- **Conductor MCP tools** — start/send/stop/status for conductor workflows
- **OpenAI Agents SDK adapter** — `AIDOCSRunHooks` for `openai-agents` SDK
- **Dashboard** — Tauri desktop app with monitoring, conductor, skills, MCP registry, settings pages
- **1287 tests**

## What's in 2.0.0
- **Smart installer** — manifest-based three-way merge, tag-based CLAUDE.md/AGENTS.md updates

## Principles

- Files remain the only source of truth
- MCP reads, validates, and writes existing AIDOCS files — never a second canonical memory
- MCP is optional; the Markdown system works without it
- Indexes are project-wide; sessions guide retrieval, not index scope
- SQLite indexes are derived only — rebuildable from files

## Install

```bash
pip install aidocs-mcp              # from PyPI
pip install aidocs-mcp[dev]         # with pytest
pip install aidocs-mcp[ast]         # with tree-sitter for JS/TS AST parsing
```

Or from source:
```bash
cd mcp
pip install -e ".[dev,ast]"
```

## Gate Architecture

6-level cascade, first match wins:

| Level | Gate | Action |
|-------|------|--------|
| 1 | Managed Mode | Block raw file tools when managed |
| 2 | Infrastructure | Block writes to aidocs.toml, aidocs_mcp/* |
| 3 | Sensitive Files | Block .env, credentials, keys |
| 4 | Memory Path | .MEMORY/ reads free, workflow writes intent-gated |
| 5 | Read Gate | Per-file discovery, `known_exact_path` bypass |
| 6 | Edit Gate | Requires prior read/discovery |

## Architecture

```
mcp/
  server/aidocs_mcp/        # Python service modules
    mcp_server.py            # FastMCP tool registration
    access_gate.py           # Unified 6-level security cascade
    service_hub.py           # Composition root
    runtime_service.py       # High-level orchestration
    session_store.py         # Session CRUD + lifecycle
    memory_store.py          # Memory read/write/capture
    code_index_store.py      # Code symbol/dependency/text search index
    file_ops.py              # File edit operations with gate integration
    server_code_tools.py     # Code search/find/trace/bundle tools
    server_code_edit_tools.py # Code edit/create/replace tools
    server_session_tools.py  # Session management tools
    ...
  pyproject.toml
  README.md
```

## Tool Model

85+ tools organized by purpose. Agents should start with entry points, not memorize all tools.

### Entry Points

- `orchestrate` — `/aidocs` bootstrap/orchestration
- `classify_prompt` + `route_prompt` — advisory routing
- `code_investigate` — broad "start here" investigation
- `code_find` — unified symbol/reference search
- `code_trace` — relationship tracing
- `code_bundle` — context retrieval
- `schema_query` — database schema

### Core Runtime

- managed mode: `mode_get`, `mode_set`, `mode_clear`
- sessions: `session_start`, `session_list`, `session_select`, `session_create`
- tasks: `task_begin`, `task_update`, `task_complete`
- memory: `memory_read`, `memory_capture`, `memory_search`
- project: `project_init`, `project_bootstrap_or_resume`, `project_sync_indexes`

### Code Operations

- read: `code_get_lines`, `code_text_search`, `code_search`
- edit: `code_edit_lines`, `code_str_replace`, `code_batch_str_replace`, `code_batch_edit`
- create: `code_create_file`, `code_insert_lines`
- analysis: `code_find_dead_code`, `code_find_stale_references`, `code_suggest_extractions`

### Precision Helpers

- `code_get_method_signature` / `code_get_method_signatures`
- `code_get_constructor_params` / `code_get_constructor_params_batch`
- `code_get_enum_values`, `code_get_entity_properties`, `code_get_service_api`

## Run

```bash
pip install aidocs-mcp
aidocs --version
aidocs-mcp   # start MCP server
```
