arkon - Moses Yebei

Abstract

Arkon: Enterprise AI Knowledge Hub & MCP Server. Self-hosted knowledge base for teams to manage RAG contexts, access policies, and AI skills. Connect Claude and other LLMs via Model Context Protocol (MCP) for automated, secure organizational knowledge integration.

The Problem

Teams adopting LLMs face a context problem: internal knowledge lives in scattered documents, gets copy-pasted into chatbots, and reaches models without access control or traceability. Arkon addresses this by centralizing organizational knowledge into a permission-scoped wiki served to AI clients through a single MCP endpoint.

What This Does

Arkon is a self-hosted knowledge management layer with a Python/Django-style backend (app/) and a Next.js frontend (frontend/). The core is an MRP pipeline (app/ai/mrp/) that maps source documents, reduces them into structured wiki pages, plans changes for human review, merges new content with existing pages, and verifies claims against source material. Every page tracks which documents it was compiled from.

The system exposes a Model Context Protocol server (app/mcp/server.py) that lets Claude and other LLM clients query the wiki through a single permission-scoped endpoint. Access control is enforced at the API, MCP, and search layers via a permission engine (app/services/permission_engine.py) with department-level and global scopes.

How It Is Wired

Execution starts at app/main.py, which mounts the FastAPI application, the MCP server at app/mcp/server.py, and routers under app/routers/. The wiki router (app/routers/wiki.py) handles page CRUD, drafts, and branches; the sources router (app/routers/sources.py) handles document ingestion. Both route through app/services/wiki_service.py and app/services/kb_service.py, which write to the PostgreSQL database via app/database/repository.py and app/database/models.py.

The MRP pipeline is the highest-blast-radius component. app/ai/mrp/pipeline.py orchestrates mapper, reducer, planner, merger, verifier, and writer stages (mapper.py, reducer.py, merger.py, verifier.py, writer.py). A pipeline run makes multiple LLM API calls per document, then writes wiki pages and source references to the database. The pipeline is resumable — drafts persist mid-run, so a crash doesn't repeat expensive LLM work.

The frontend is a standard Next.js app under frontend/src/app/, with pages for wiki browsing, knowledge graph visualization, admin settings, and audit logs. It talks to the backend via REST endpoints. The app/worker.py file suggests background task processing, though the exact worker framework isn't documented in the structure.

Database migrations live in alembic/versions/ — 36 migrations covering schema evolution from initial tables through RBAC, wiki branches, and multi-dimensional embeddings. The alembic/env.py handles migration execution.

How To Use It

Setup: Docker is the primary path — docker-compose.yml at the root defines the full stack (backend, frontend, PostgreSQL). Build with:

docker compose up --build

Configuration: Copy .env.docker.example to .env and set database credentials, LLM API keys (Anthropic, OpenAI, Google providers are supported via app/ai/providers/), and OAuth settings. The app/config.py file loads these.

Running it: The Docker entry point (entrypoint.sh) starts the backend and applies migrations. For development, run the backend with uvicorn app.main:app and the frontend with npm run dev in frontend/.

Real-World Use

An HR team connects Claude Desktop to Arkon via OAuth. When an employee asks about parental leave policy, the MCP server routes the query through the permission engine, returns only pages from the HR department scope, and includes source citations. An editor ingests a new policy PDF via the sources router; the MRP pipeline generates a plan, the editor approves it, and the wiki updates without losing prior content.

Code Health & Issues

Med - No CI/CD pipeline - no .github/ directory or CI config exists, so there's no automated build or test gate.
Low - Test coverage is thin - 8 test files across the entire repo, none covering the MRP pipeline or MCP server directly.
Low - License is restrictive - PolyForm Internal Use 1.0.0 permits internal use but not redistribution or commercial SaaS offerings.

The Bottom Line

Arkon is a serious, well-architected answer to the enterprise AI context problem. The MRP pipeline and permission scoping are genuinely differentiated. The lack of CI and thin test coverage are the main risks for a team adopting it. It's a strong fit for organizations that need controlled, traceable AI access to internal knowledge and can invest in hardening the deployment pipeline.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

302 files

Python136
TSX102
Markdown18
TypeScript11
JSON6
CSS2

ReactNext.jsDjangoDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["frontend<br/>115 modules"] g1["app<br/>89 modules"] g2["alembic<br/>38 modules"] g3["tests<br/>8 modules"] g3 -->|11| g1 g2 -->|3| g1

Module dependencies

The 10 most depended-upon modules of 251, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_app_database_models["models"] n1_app_database___init__["__init__"] n2_app_services_auth_service["auth_service"] n3_app_services___init__["__init__"] n4_app_config["config"] n5_app_ai_registry["registry"] n6_p_services_permission_engine["permission_engine"] n7_app_ai_providers_base["base"] n8_app_services_storage_service["storage_service"] n9_app_services_audit_service["audit_service"] n5_app_ai_registry --> n7_app_ai_providers_base n1_app_database___init__ --> n4_app_config n9_app_services_audit_service --> n0_app_database_models n2_app_services_auth_service --> n4_app_config n2_app_services_auth_service --> n1_app_database___init__ n2_app_services_auth_service --> n0_app_database_models n2_app_services_auth_service --> n6_p_services_permission_engine n6_p_services_permission_engine --> n0_app_database_models n8_app_services_storage_service --> n4_app_config

Dependencies

13 of 61 declared dependencies are a major version behind. Resolved 61 of 61 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^20	26.2.0	6 major
`cryptography`	>=44.0	50.0.0	6 major
`redis`	>=5.0	8.1.0	3 major
`typescript`	^5	7.0.2	2 major
`openai`	>=1.30.0	3.1.0	2 major
`aiosmtplib`	>=3.0.0	5.1.2	2 major
`@types/diff`	^7.0.2	8.0.0	1 major
`eslint`	^9	10.8.1	1 major

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium4

Commit a lockfile beside the manifesthigh

pyproject.toml

manifest with no lockfile in scope

An unlocked range means the artifact you tested and the artifact you ship can contain different transitive code, so a malicious patch release reaches production with no diff.

Fix: Run the package manager once and commit the generated lockfile.

Add a workflow that builds and tests this repositoryhigh

251 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh3 occurrences

Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Give the outbound request a timeoutmedium

docker-compose.yml

1 outbound call(s) with no timeout

requests has no default timeout, so a peer that accepts the connection and then says nothing holds the worker forever, and with a small worker pool a single slow dependency takes the whole service down without anything appearing to fail.

Fix: Pass timeout= on every call, or use a session with one configured.

Expand the test suite; it cannot cover this codebasemedium8 occurrences

8 test files against 251 source files (ratio 0.032)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.