uni-kb — Knowledge Base Library

Reusable data layer for codebase understanding. Parses source code into structured knowledge, indexes it for search, and serves it via MCP.

Can be used standalone by human developers or consumed by uni-dev agent system.

Architecture

Source Code
  │
  ▼
┌──────────────────────────────────────────┐
│  tree-sitter Parsers (plugin system)     │
│  Java/Spring · Node.js/Express/NestJS     │
└───────────────┬──────────────────────────┘
                ▼  structured JSON
┌──────────────────────────────────────────┐
│  Storage Layer                            │
│  ┌──────────┬──────────┬───────────────┐ │
│  │ SQLite   │ ChromaDB │ NetworkX      │ │
│  │ 8 tables │ 14 idx   │ Code Graph    │ │
│  └──────────┴──────────┴───────────────┘ │
└───────────────┬──────────────────────────┘
                ▼
┌──────────────────────────────────────────┐
│  Spec Generators (6)                      │
│  API Contract · Business Logic · Models   │
│  Auth Matrix · Config · Migration         │
└───────────────┬──────────────────────────┘
                ▼
┌──────────────────────────────────────────┐
│  MCP Server (20 tools, 5 categories)      │
└──────────────────────────────────────────┘

Phase 1: Parser Extension System

Goal: Abstract plugin interface + registry + Java parser

1.1 Base Plugin Interface (parsers/base.py)

class ParserPlugin(ABC):
    @abstractmethod
    def language(self) -> str: ...
    @abstractmethod
    def detect(self, file_path: str) -> bool: ...
    @abstractmethod
    def parse(self, file_path: str, source: str) -> ParseResult: ...

1.2 Plugin Registry (parsers/registry.py)

Discovers plugins via Python entry points (pyproject.toml [project.entry-points."uni_kb.parsers"]). Loads on demand.

1.3 Java Parser (parsers/java/)

Four sub-parsers using tree-sitter-java:

Parser	Target	Extracts
controller.py	@RestController, @RequestMapping	Endpoints, HTTP methods, paths, params, response types
service.py	@Service, method bodies	Business logic structure, dependencies
entity.py	@Entity, @Column, @Table	Entities, fields, types, constraints, relationships
mapper.py	MyBatis XML	Custom SQL queries, result maps

Output: ParseResult with standardized JSON matching SQLite schema.

Phase 2: Storage Layer

2.1 SQLite Store (store/sqlite_store.py)

8 tables initialized on uni-kb init --project ./:

Table	Purpose
modules	Top-level source modules
classes	Classes / components
methods	Methods / functions
api_endpoints	REST endpoints
db_tables	Database tables
db_columns	Table columns
frontend_components	Vue/Cocos components
auth_permissions	Permission annotations

2.2 ChromaDB Indexes (store/chroma_indexes.py)

14 named collections with embedded mode (persisted in .uni-kb/chroma/):

#	Index	Content
1	code_java_controller	Java controller source
2	code_java_service	Java service source
3	code_java_entity	Java entity source
4	code_java_mapper	Mapper XML source
5	code_typescript_admin	Vue admin source
6	code_typescript_game	Cocos game source
7	specs_api	Generated OpenAPI specs
8	specs_business_logic	Generated method docs
9	specs_data_model	Generated entity specs
10	specs_auth	Permission matrix
11	specs_config	Config catalog
12	db_schema	Table DDL
13	project_docs	Documentation
14	migration_checklists	Per-module checklists

2.3 Code Graph (store/code_graph.py)

NetworkX directed graph.

Nodes (8 types): Module, Class, Method, APIEndpoint, DBTable, DBColumn, VueComponent, CocosComponent

Edges (11 + 3 migration): HAS_METHOD, CALLS, INJECTS, IMPLEMENTS, EXTENDS, ROUTES_TO, MAPS_TO, FK_TO, API_CALLER, PERMITS, IMPORTS + MIGRATES_TO, BLOCKED_BY, VERIFIED_AGAINST

Phase 3: Node.js Parser

1.4 Node.js Parser (parsers/nodejs/)

Four sub-parsers using tree-sitter-typescript:

Parser	Target	Extracts
route.py	Express router.get() / NestJS @Get()	Endpoints, HTTP methods, paths, middleware chains
service.py	Service classes	Business logic structure
model.py	Sequelize / TypeORM models	Entities, fields, types, relationships
middleware.py	Auth middleware	Permission chains, guards

Phase 4: Spec Generators + MCP

4.1 Generators (generators/)

6 generators, 4 exposed as direct MCP tools:

Generator	Input	Output	MCP Tool
api_contract.py	Controller/Route AST	OpenAPI 3.0 YAML	get_api_contract
business_logic.py	Service AST	Markdown pseudo-code	get_business_logic_doc
data_model.py	Entity + DB schema	YAML model spec	→ get_entity_spec
auth_matrix.py	Permission annotations	Permission matrix YAML	get_permission_matrix
config_catalog.py	YAML/.env files	Config catalog YAML	→ get_config_value
migration_checklist.py	Module + dep graph	Prioritized checklist MD	get_migration_checklist

4.2 MCP Server (mcp_server.py)

20 tools in 5 categories:

Category	Tools
Code Exploration	search_code, get_method_body, get_class_structure, find_endpoints, find_usages
Spec Retrieval	get_api_contract, get_business_logic_doc, verify_contract, compare_api_responses
Data Model	get_entity_spec, get_db_schema, get_column_info, trace_fk_chain
Auth & Config	get_permission_matrix, get_config_value, get_config_catalog
Operations	get_migration_checklist, get_dependency_graph, get_migration_status, run_test_suite

Dependencies

chromadb
networkx
tree-sitter
tree-sitter-java
tree-sitter-typescript
sqlite-utils
pyyaml
mcp>=1.0.0

CLI Usage

# Initialize knowledge base for a project
uni-kb init --project /path/to/project

# Parse and index source code
uni-kb index --project /path/to/project

# Start MCP server
uni-kb serve --project /path/to/project --port 9020