Which integrations are available for this server?

Allows connecting to Confluence (Cloud or Server) to ingest space pages as knowledge sources for ACO compilation. Allows connecting a GitHub Wiki to ingest wiki pages as knowledge sources for ACO compilation. Allows connecting a Notion workspace to ingest pages and databases as knowledge sources for ACO compilation. Allows connecting an Obsidian vault to ingest notes, resolving wiki links, tags, and backlinks for ACO compilation.

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@aco compose a coder context pack for implementing the payment service" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

aco

by flyingfan76

Overview Schema Source Related Servers Discussions Admin

Python

Local

ACO — Agent Context OS

A continuous engineering knowledge compiler and MCP runtime.

ACO ingests your existing engineering docs — ADRs, OpenAPI specs, AI-generated analyses, Markdown, PDFs, Word docs, Notion pages, GitHub Wikis, Confluence spaces, Obsidian vaults — compiles them into typed, code-anchored Knowledge Objects, detects when your code drifts away from documented decisions, and serves structured context to AI coding agents via MCP.

docs/adr/*.md  ──┐
openapi.yaml   ──┤
notion pages   ──┤
confluence     ──┤  aco compile  ──►  Knowledge Graph  ──►  AI Agent context
obsidian vault ──┤                    (typed, anchored,      (via MCP or CLI)
pdf/docx       ──┤                     drift-detected,
ai-exports/    ──┘                     semantically indexed)

Related MCP server: codegraph-ai

Requirements

Python 3.12+
uv — brew install uv or pip install uv

Installation

Option A — uv tool (recommended, global install)

git clone https://github.com/<your-username>/aco.git
cd aco
uv tool install .
aco --help

Option B — editable install in virtualenv

git clone https://github.com/<your-username>/aco.git
cd aco
uv sync
uv run aco --help

Option C — pipx

git clone https://github.com/<your-username>/aco.git
pipx install ./aco
aco --help

Quick Start

# 1. Initialize a workspace pointing at your project
aco workspace init /path/to/your/project --name "My Project"
# → Workspace created: ws_abc123...

# 2. Add a knowledge source
aco source add --workspace ws_abc123 \
  --connector builtin/local-fs \
  --name "ADRs" \
  --root /path/to/your/project/docs/adr \
  --globs "**/*.md"

# 3. Compile
aco compile run --workspace ws_abc123

# 4. See what was found
aco knowledge list --workspace ws_abc123

# 5. Get a context pack
aco assembly compose --workspace ws_abc123 \
  --role coder \
  --goal "implement the payment service" \
  --path src/payments/handler.py

Standalone Usage

Workspace management

aco workspace init /path/to/project --name "My Project"
aco workspace list
aco workspace info --workspace ws_<id>
aco workspace remove ws_<id> --confirm

Sources

ACO supports six built-in connectors and two additional file parsers:

Connector	Use case
`builtin/local-fs`	Local Markdown, ADRs, OpenAPI specs, PDFs, Word docs
`builtin/ai-export`	Exported ChatGPT / Claude / Cursor conversations
`builtin/notion`	Notion workspace pages and databases
`builtin/github-wiki`	GitHub Wiki pages
`builtin/confluence`	Confluence space pages (Cloud or Server)
`builtin/obsidian`	Obsidian vault — resolves wiki links, tags, backlinks

Supported file types: .md, .yaml/.json (OpenAPI), .pdf, .docx

# Local filesystem (auto-detects PDF/docx by MIME type)
aco source add --workspace ws_<id> \
  --connector builtin/local-fs \
  --name "Docs" \
  --root docs/ \
  --globs "**/*.md" "**/*.pdf" "**/*.docx"

# AI export archive
aco source add --workspace ws_<id> \
  --connector builtin/ai-export \
  --name "AI Exports" \
  --archive-path /path/to/exports.tar.gz

# Notion workspace
aco source add --workspace ws_<id> \
  --connector builtin/notion \
  --name "Notion Docs" \
  --token secret_xxx \
  --database-id db_id_1

# GitHub Wiki
aco source add --workspace ws_<id> \
  --connector builtin/github-wiki \
  --name "Wiki" \
  --token ghp_xxx \
  --repo owner/repo-name

# Confluence (API token)
aco source add --workspace ws_<id> \
  --connector builtin/confluence \
  --name "Confluence" \
  --base-url https://company.atlassian.net \
  --token base64token \
  --space-key TEAM

# Confluence (cookie file — e.g. from sap-auth-mcp)
aco source add --workspace ws_<id> \
  --connector builtin/confluence \
  --name "SAP Wiki" \
  --base-url https://wiki.company.com \
  --cookie-file ~/.cookies/wiki.json \
  --space-key ENG

# Obsidian vault
aco source add --workspace ws_<id> \
  --connector builtin/obsidian \
  --name "My Vault" \
  --vault-path /path/to/obsidian-vault

aco source list --workspace ws_<id>
aco source fetch --workspace ws_<id>   # re-fetch without full compile

Compiling

aco compile run --workspace ws_<id>              # full pipeline (includes embed)
aco compile run --workspace ws_<id> --stage fetch  # single stage
aco compile run --workspace ws_<id> --stage embed  # re-embed only
aco compile status --workspace ws_<id>
aco compile logs <job_id>

Knowledge objects

ACO extracts 10 object types: ArchitectureDecision, Requirement, Constraint, APISpec, Runbook, GlossaryTerm, Risk, QualityAttribute, TechDependency, DesignInsight.

aco knowledge list --workspace ws_<id>
aco knowledge list --workspace ws_<id> --type ArchitectureDecision --status ACTIVE
aco knowledge show <object_id>
aco knowledge approve <object_id>   # promote REVIEW_REQUIRED → ACTIVE
aco knowledge reject <object_id>
aco knowledge verify --workspace ws_<id>   # manual drift check

Review queue

AI-generated objects (DesignInsight) always land in REVIEW_REQUIRED before becoming active:

aco review list --workspace ws_<id>
aco review show <review_id>
aco review approve <review_id>
aco review reject <review_id> --reason "outdated"
aco review approve-all --workspace ws_<id> --type DesignInsight --confirm

Assembly — context packs for agents

aco assembly compose --workspace ws_<id> \
  --role coder \
  --goal "refactor the auth module" \
  --path src/auth/handler.py \
  --path src/auth/models.py \
  --budget 8000 \
  --format markdown   # or json, xml

Roles: coder · reviewer · architect · debugger · security

Each role shapes the same Knowledge Objects differently — a coder pack emphasises implementation anchors and constraints; a reviewer pack emphasises decision rationale and risks.

Continuous compilation via git hooks

# Install — writes a post-commit hook into your project's .git
aco hooks install --workspace ws_<id> --git-dir /path/to/project/.git

# Every commit now auto-runs drift detection.
# Objects whose anchored code has changed move to DRIFTED.

# Remove
aco hooks remove --git-dir /path/to/project/.git

Portability

# Export full workspace state to a portable archive
aco pack export --workspace ws_<id> --out ~/backups/my-project.acopack.tar.gz

# Import on any machine
aco pack import ~/backups/my-project.acopack.tar.gz

Usage with Claude Code (MCP)

ACO exposes a full MCP server over stdio, giving Claude Code access to your Knowledge Graph as tools.

1. Configure Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aco": {
      "command": "aco",
      "args": ["mcp-serve", "--workspace", "ws_<your-workspace-id>"]
    }
  }
}

If you installed via uv without global install:

{
  "mcpServers": {
    "aco": {
      "command": "uv",
      "args": ["run", "aco", "mcp-serve", "--workspace", "ws_<id>"],
      "cwd": "/path/to/aco"
    }
  }
}

Restart Claude Code — the ACO tools appear under /mcp.

2. Available MCP tools

Tool	What it does
`assembly.compose`	Get a token-budgeted context pack for the current task
`knowledge.list`	List Knowledge Objects by type / status
`knowledge.get`	Full object detail with provenance
`knowledge.approve` / `reject`	Review AI-generated objects
`knowledge.verify`	Trigger drift detection
`review.list` / `approve` / `reject`	Manage the review queue
`compiler.run`	Trigger a compile job
`compiler.status`	Check job progress
`task.create` / `session.start` / `artifact.save`	Track agent work
`workspace.info` / `source.list`	Inspect workspace state

3. Typical session flow

Before starting work:

"Use assembly.compose with role=coder, goal='implement rate limiting', focal_paths=['src/api/middleware.py'] to get relevant context."

Claude receives a structured pack of Architecture Decisions, Constraints, and API Specs anchored to that file — injected as context for the session.

After committing:

The git hook auto-detects drift. Claude can check:

"Run knowledge.verify to see if any Knowledge Objects drifted."

Reviewing AI insights:

"Show me the review queue and approve the DesignInsight objects."

Migrating to a New Machine

ACO state lives entirely in ~/.aco/ — the workspace directory itself is not touched. Migration is straightforward.

Method 1: Pack export/import (recommended)

# On the old machine — export each workspace
aco workspace list   # note workspace IDs
aco pack export --workspace ws_<id> --out ~/ws-myproject.tar.gz

# Copy to new machine
scp ~/ws-myproject.tar.gz newmachine:~/

# On the new machine — install ACO, then import
aco pack import ~/ws-myproject.tar.gz

# Re-register the workspace path (the registry stores the absolute path to your project)
aco workspace list   # verify it imported

Note: After import, if your project lives at a different path on the new machine, update the registry:
# Edit ~/.aco/registry.json — change the "path" value for your workspace ID

Method 2: Copy state root directly

# On the old machine
tar -czf aco-state.tar.gz ~/.aco/

# Copy and restore on new machine
scp aco-state.tar.gz newmachine:~/
ssh newmachine "tar -xzf ~/aco-state.tar.gz -C ~/"

Then update any absolute paths in ~/.aco/registry.json if your project directory differs.

What state is preserved

Preserved	Not preserved
All Knowledge Objects + versions	Git hooks (re-install with `aco hooks install`)
Provenance records	Virtual environments / uv cache
Review queue
Compiler job history
Context items + projections
Workspace manifest + config

Re-installing ACO on the new machine

git clone https://github.com/<your-username>/aco.git
cd aco
uv tool install .
aco workspace list   # your workspaces are back

Core Concepts

Concept	Description
Knowledge Source	Registered origin — a local directory, OpenAPI file, or AI export archive
Document	Original file fetched from a source, versioned by SHA-256
Knowledge Object	Typed, structured fact extracted from documents (Decision, Constraint, API, etc.)
Object Anchor	Link from a Knowledge Object to a code location; drives drift detection
Context Item	Assembly-ready prompt fragment projected from a Knowledge Object
Assembly Pack	Token-budgeted bundle of Context Items composed for a specific agent role and task
Drift	An Object Anchor's code SHA changed — the object moves to `DRIFTED` until reviewed
State root	`~/.aco/` — all ACO state; zero files written to your project repo

Object lifecycle

DRAFT → ACTIVE          (rule/human-extracted, passes validation)
DRAFT → REVIEW_REQUIRED (AI-extracted — always requires human approval)
ACTIVE → DRIFTED        (anchored code changed)
DRIFTED → REFRESHING    (refresh triggered)
REFRESHING → ACTIVE     (human approves updated version)

LLM-based Extraction

Use an LLM (Claude or OpenAI) to extract Knowledge Objects from unstructured documents — meeting notes, Notion pages, Confluence articles — where there's no MADR or OpenAPI structure to parse.

Install the LLM extras:

uv sync --extra anthropic   # Claude
uv sync --extra openai      # OpenAI
uv sync --extra llm         # both

Configure a source to use LLM extraction:

aco source add --workspace ws_<id> \
  --connector builtin/local-fs \
  --name "Meeting Notes" \
  --root docs/meetings \
  --globs "**/*.md"

Then edit the source config in ~/.aco/workspaces/<ws_id>/metadata.sqlite to add the extractor key, or use aco source add --config-json:

{
  "root": "docs/meetings",
  "globs": ["**/*.md"],
  "exclude": [],
  "extractor": "builtin/llm",
  "provider": "anthropic",
  "model": "claude-sonnet-5",
  "api_key_env": "ANTHROPIC_API_KEY",
  "object_types": ["Requirement", "Constraint", "Risk", "GlossaryTerm"],
  "max_objects_per_doc": 20
}

All LLM-extracted objects land in REVIEW_REQUIRED automatically — they require human approval before entering the Knowledge Graph.

export ANTHROPIC_API_KEY=sk-ant-...
aco compile run --workspace ws_<id>
aco review list --workspace ws_<id>
aco review approve-all --type Constraint --confirm

Vector Embeddings + Semantic Search

Enable semantic similarity search so assembly compose can find relevant Knowledge Objects even when they don't share code anchors with the files you're working on.

Add to your ~/.aco/workspaces/<ws_id>/manifest.toml:

[embeddings]
enabled = true
provider = "anthropic"           # or "openai"
model = "voyage-3"               # text-embedding-3-small for OpenAI
api_key_env = "ANTHROPIC_API_KEY"
dimensions = 1024
similarity_threshold = 0.75
max_semantic_candidates = 10

Compute embeddings:

aco compile run --workspace ws_<id> --stage embed
# or included automatically in a full compile:
aco compile run --workspace ws_<id>

Once indexed, assembly compose automatically uses semantic retrieval when goal is provided and the manifest has embeddings enabled — no extra flags needed:

aco assembly compose --workspace ws_<id> \
  --role coder \
  --goal "implement rate limiting for the auth service"
# → finds relevant Constraints, Risks, and Architecture Decisions
#   even if they're not anchored to the exact file you're editing

Core Concepts

Concept	Description
Knowledge Source	Registered origin — local directory, Notion workspace, GitHub Wiki, Confluence space, AI export
Document	Original file fetched from a source, versioned by SHA-256
Knowledge Object	Typed, structured fact extracted from documents (Decision, Constraint, API, etc.)
Object Anchor	Link from a Knowledge Object to a code location; drives drift detection
Context Item	Assembly-ready prompt fragment projected from a Knowledge Object
Assembly Pack	Token-budgeted bundle of Context Items composed for a specific agent role and task
Drift	An Object Anchor's code SHA changed — the object moves to `DRIFTED` until reviewed
State root	`~/.aco/` — all ACO state; zero files written to your project repo

Object lifecycle

DRAFT → ACTIVE          (rule/human-extracted, passes validation)
DRAFT → REVIEW_REQUIRED (AI-extracted — always requires human approval)
ACTIVE → DRIFTED        (anchored code changed)
DRIFTED → REFRESHING    (refresh triggered)
REFRESHING → ACTIVE     (human approves updated version)

Deferred (v0.12+)

Cross-workspace federation
Vector store backend for workspaces with >10k objects
PDF/docx image extraction
Obsidian Canvas files (.canvas)
Notion/GitHub Wiki/Confluence/Obsidian watch mode (real-time sync)
OpenTelemetry

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

memsprout AOAuth
com.memsprout
shared AI-context layer for teams — persistent memory your agents search and update over MCP
Knowledge & Memory RAG Systems
2
ctx A
io.github.vanshulgoyal101
Turn a GitHub repo or docs site into agent-ready context: pack it or search it, over MCP.
RAG Systems Search Documentation Access
611
Cortex C
io.cortex.mcp
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Developer Tools Monitoring Observability
312
gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5364

Related MCP Servers

logicstamp-mcpofficial
Developer Tools Code Analysis
LogicStamp
A
license
A
quality
C
maintenance
MCP server that provides AI assistants with structured access to codebases via LogicStamp Context, enabling component analysis, dependency graphs, drift detection, and token-optimized context delivery.
Updated 5 months ago (2026-04-15 16:13 UTC)
7
8 npm
4
MIT
codegraph-ai
Code Analysis Developer Tools
jotaseme
A
license
Not graded
quality
D
maintenance
Serves structured code context via MCP, enabling AI agents to understand codebases with dependency graphs and significantly reduce token usage.
Updated 7 months ago (2026-02-24 16:13 UTC)
13 npm
MIT
contextsliver
Code Analysis Knowledge & Memory Developer Tools
DevMuneeb
A
license
Not graded
quality
A
maintenance
An MCP server that indexes codebases into a local graph and provides on-demand context retrieval for AI coding agents, reducing token usage by tracking session history and delivering only relevant code subgraphs.
Updated 2 months ago (2026-07-24 18:02 UTC)
7 npm
MIT
Repo Context Forge
Code Analysis Version Control Developer Tools
negativexq
A
license
A
quality
B
maintenance
MCP server that inspects local codebases and generates source-grounded context packs for coding agents, with tools for repository search, symbols, dependencies, Git analysis, and context generation.
Updated 2 months ago (2026-08-04 23:51 UTC)
6
MIT

ACO — Agent Context OS

Table of Contents

Requirements

Installation

Option A — uv tool (recommended, global install)

Option B — editable install in virtualenv

Option C — pipx

Quick Start

Standalone Usage

Workspace management

Sources

Compiling

Knowledge objects

Review queue

Assembly — context packs for agents

Continuous compilation via git hooks

Portability

Usage with Claude Code (MCP)

1. Configure Claude Code

2. Available MCP tools

3. Typical session flow

Migrating to a New Machine

Method 1: Pack export/import (recommended)

Method 2: Copy state root directly

What state is preserved

Re-installing ACO on the new machine

Core Concepts

Object lifecycle

LLM-based Extraction

Vector Embeddings + Semantic Search

Core Concepts

Object lifecycle

Deferred (v0.12+)

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

logicstamp-mcpofficial

codegraph-ai

contextsliver

Repo Context Forge