@codifier/cli 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +511 -0
- package/commands/init.md +3 -0
- package/commands/onboard.md +3 -0
- package/commands/research.md +3 -0
- package/dist/cli/add.d.ts +5 -0
- package/dist/cli/add.d.ts.map +1 -0
- package/dist/cli/add.js +23 -0
- package/dist/cli/add.js.map +1 -0
- package/dist/cli/bin/codifier.d.ts +7 -0
- package/dist/cli/bin/codifier.d.ts.map +1 -0
- package/dist/cli/bin/codifier.js +43 -0
- package/dist/cli/bin/codifier.js.map +1 -0
- package/dist/cli/detect.d.ts +12 -0
- package/dist/cli/detect.d.ts.map +1 -0
- package/dist/cli/detect.js +35 -0
- package/dist/cli/detect.js.map +1 -0
- package/dist/cli/doctor.d.ts +5 -0
- package/dist/cli/doctor.d.ts.map +1 -0
- package/dist/cli/doctor.js +58 -0
- package/dist/cli/doctor.js.map +1 -0
- package/dist/cli/init.d.ts +6 -0
- package/dist/cli/init.d.ts.map +1 -0
- package/dist/cli/init.js +93 -0
- package/dist/cli/init.js.map +1 -0
- package/dist/cli/update.d.ts +5 -0
- package/dist/cli/update.d.ts.map +1 -0
- package/dist/cli/update.js +25 -0
- package/dist/cli/update.js.map +1 -0
- package/dist/index.js +87 -0
- package/package.json +40 -0
- package/skills/brownfield-onboard/SKILL.md +107 -0
- package/skills/initialize-project/SKILL.md +145 -0
- package/skills/initialize-project/templates/evals-prompt.md +39 -0
- package/skills/initialize-project/templates/requirements-prompt.md +44 -0
- package/skills/initialize-project/templates/roadmap-prompt.md +44 -0
- package/skills/initialize-project/templates/rules-prompt.md +34 -0
- package/skills/research-analyze/SKILL.md +131 -0
- package/skills/research-analyze/templates/query-generation-prompt.md +61 -0
- package/skills/research-analyze/templates/synthesis-prompt.md +67 -0
- package/skills/shared/codifier-tools.md +123 -0
package/README.md
ADDED
|
@@ -0,0 +1,511 @@
|
|
|
1
|
+
# CodifierMcp
|
|
2
|
+
|
|
3
|
+
**Institutional Memory for AI-Driven Development — Across Every Org Role**
|
|
4
|
+
|
|
5
|
+
CodifierMcp is a remote MCP (Model Context Protocol) server that gives AI assistants shared, persistent organizational knowledge. It captures learnings, decisions, and research findings from any team member — and surfaces them to any other member — creating a feedback loop that makes the organization smarter over time.
|
|
6
|
+
|
|
7
|
+
[](https://nodejs.org/)
|
|
8
|
+
[](https://www.typescriptlang.org/)
|
|
9
|
+
[](https://modelcontextprotocol.io/)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Table of Contents
|
|
14
|
+
|
|
15
|
+
- [Overview](#overview)
|
|
16
|
+
- [Key Capabilities](#key-capabilities)
|
|
17
|
+
- [Architecture](#architecture)
|
|
18
|
+
- [Use Cases](#use-cases)
|
|
19
|
+
- [Prerequisites](#prerequisites)
|
|
20
|
+
- [Installation](#installation)
|
|
21
|
+
- [Configuration](#configuration)
|
|
22
|
+
- [Environment Variables](#environment-variables)
|
|
23
|
+
- [MCP Client Configuration](#mcp-client-configuration)
|
|
24
|
+
- [MCP Tools](#mcp-tools)
|
|
25
|
+
- [Skills](#skills)
|
|
26
|
+
- [Developer Skills](#developer-skills)
|
|
27
|
+
- [Researcher Skills](#researcher-skills)
|
|
28
|
+
- [Remote Server (HTTP Mode)](#remote-server-http-mode)
|
|
29
|
+
- [Development](#development)
|
|
30
|
+
- [Architecture Details](#architecture-details)
|
|
31
|
+
- [Roadmap](#roadmap)
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Overview
|
|
36
|
+
|
|
37
|
+
CodifierMcp bridges the gap between AI assistants and your organization's institutional knowledge. Instead of starting from scratch in every session, AI assistants can:
|
|
38
|
+
|
|
39
|
+
1. **Fetch Context**: Retrieve relevant rules, guidelines, decisions, and research findings from the shared knowledge base
|
|
40
|
+
2. **Update Memory**: Save new insights, patterns, and learnings discovered during development or research
|
|
41
|
+
3. **Follow Skills**: Walk through guided, conversational workflows that produce structured artifacts (rules, roadmaps, research reports)
|
|
42
|
+
4. **Integrate with Data Sources**: Pull in repo code via RepoMix and query data warehouses via Athena
|
|
43
|
+
|
|
44
|
+
This creates a virtuous cycle where knowledge from a developer's session informs a researcher's analysis, and vice versa.
|
|
45
|
+
|
|
46
|
+
### Key Capabilities
|
|
47
|
+
|
|
48
|
+
1. **Org-scoped knowledge persistence** — Learnings from any person, any role, any project persist in a shared, searchable KB. A developer's discovery about a legacy API informs a researcher's analysis six months later.
|
|
49
|
+
|
|
50
|
+
2. **Authenticated connectors to proprietary data** — RepoMix for private code repositories; AWS Athena for data warehouses. Future: SharePoint, Confluence, Google Drive.
|
|
51
|
+
|
|
52
|
+
3. **Guided friction reduction via Skills** — Role-specific conversational workflows. Developers get project initialization with rules and roadmaps. Researchers get data discovery and synthesis. The LLM reads the Skill and guides the conversation — no choppy step-by-step protocol.
|
|
53
|
+
|
|
54
|
+
4. **Multi-surface access** — IDE via MCP (Cursor, Claude Code, Claude Desktop). CLI installer (`npx codifier init`). Future: Teams bot.
|
|
55
|
+
|
|
56
|
+
### Architecture
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
┌──────────────────────────────────────────────────────┐
|
|
60
|
+
│ MCP Clients │
|
|
61
|
+
│ (Claude Desktop, Cursor, Claude Code) │
|
|
62
|
+
│ │
|
|
63
|
+
│ Skills (.codifier/skills/) ← npx codifier init │
|
|
64
|
+
│ Slash Commands (.claude/commands/ or .cursor/rules/)│
|
|
65
|
+
└──────┬──────────────────────────┬────────────────────┘
|
|
66
|
+
│ stdio (local) │ SSE/HTTP (remote)
|
|
67
|
+
↓ ↓
|
|
68
|
+
┌─────────────────────────────────────────┐
|
|
69
|
+
│ CodifierMcp Server │
|
|
70
|
+
│ ├── Transport: stdio | SSE │
|
|
71
|
+
│ ├── Auth: Bearer token middleware │
|
|
72
|
+
│ └── MCP Tools (5) │
|
|
73
|
+
│ fetch_context / update_memory │
|
|
74
|
+
│ manage_projects / pack_repo │
|
|
75
|
+
│ query_data │
|
|
76
|
+
└──────┬──────────────────────────────────┘
|
|
77
|
+
│
|
|
78
|
+
┌────┴────────────────────────────────┐
|
|
79
|
+
│ Supabase (PostgreSQL + pgvector) │
|
|
80
|
+
│ projects / repositories / memories │
|
|
81
|
+
│ api_keys │
|
|
82
|
+
└─────────────────────────────────────┘
|
|
83
|
+
│
|
|
84
|
+
Direct Integrations:
|
|
85
|
+
├── RepoMix (npm programmatic API)
|
|
86
|
+
└── AWS Athena MCP (sidecar subprocess)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
**Skills are client-side.** Each Skill is a markdown instruction file the LLM reads locally. The LLM drives the conversation and calls MCP tools only for data operations. There is no server-side session state.
|
|
90
|
+
|
|
91
|
+
### Use Cases
|
|
92
|
+
|
|
93
|
+
- **Project Initialization**: Follow the Initialize Project Skill to generate Rules.md, Evals.md, Requirements.md, and Roadmap.md from a description, SOW, or existing codebase
|
|
94
|
+
- **Brownfield Onboarding**: Pack an existing repo with RepoMix and generate an architectural summary
|
|
95
|
+
- **Research & Analysis**: Define a research objective, discover Athena schema, execute queries, synthesize findings
|
|
96
|
+
- **Cross-Role Knowledge Flow**: A researcher's findings (stored as `research_finding`) are retrieved by a developer via `fetch_context` when initializing a related project
|
|
97
|
+
- **Onboarding AI Assistants**: New AI sessions automatically learn your team's conventions and decisions
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Prerequisites
|
|
102
|
+
|
|
103
|
+
### Remote Install (Recommended)
|
|
104
|
+
|
|
105
|
+
No local setup required. You need:
|
|
106
|
+
|
|
107
|
+
1. **API auth token** — obtain from your Codifier deployment admin
|
|
108
|
+
2. **MCP-compatible AI client** — Claude Desktop, Cursor, or Claude Code CLI
|
|
109
|
+
|
|
110
|
+
**Install Skills and MCP config in one command:**
|
|
111
|
+
```bash
|
|
112
|
+
npx codifier init
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
This scaffolds Skills into `.codifier/skills/`, writes slash commands to the correct client location, prompts for your server URL and API key, writes `.codifier/config.json` and the client-specific MCP config, and verifies connectivity.
|
|
116
|
+
|
|
117
|
+
### Local / Self-Hosted Prerequisites
|
|
118
|
+
|
|
119
|
+
1. **Node.js 18+** — `node --version`
|
|
120
|
+
2. **Supabase project** — free tier at [supabase.com](https://supabase.com/); requires Project URL and Service Role Key
|
|
121
|
+
3. **(Optional) AWS credentials** — for Research & Analyze Skill using Athena
|
|
122
|
+
4. **(Optional) GitHub/GitLab token** — for private repo access via RepoMix
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Installation
|
|
127
|
+
|
|
128
|
+
### Remote Install (Recommended)
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
# Scaffold Skills and MCP config into your project
|
|
132
|
+
npx codifier init
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The CLI prompts for your Codifier server URL (default: `https://codifier-mcp.fly.dev`) and API key, then:
|
|
136
|
+
- Copies all Skills to `.codifier/skills/`
|
|
137
|
+
- Writes slash commands to `.claude/commands/` (Claude Code), `.cursor/rules/` (Cursor), or `.codifier/commands/` (generic)
|
|
138
|
+
- Writes `.mcp.json` (Claude Code) or equivalent client config
|
|
139
|
+
- Verifies MCP connectivity via `GET /health`
|
|
140
|
+
|
|
141
|
+
Alternatively, configure the MCP connection manually:
|
|
142
|
+
|
|
143
|
+
```bash
|
|
144
|
+
# Claude Code CLI
|
|
145
|
+
claude mcp add --transport http codifier https://codifier-mcp.fly.dev/mcp \
|
|
146
|
+
--header "Authorization: Bearer <your-token>"
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Local / Self-Hosted Install
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
# 1. Clone
|
|
153
|
+
git clone https://github.com/yourusername/codifierMcp.git
|
|
154
|
+
cd codifierMcp
|
|
155
|
+
|
|
156
|
+
# 2. Install dependencies
|
|
157
|
+
npm install
|
|
158
|
+
|
|
159
|
+
# 3. Build
|
|
160
|
+
npm run build
|
|
161
|
+
|
|
162
|
+
# 4. Configure
|
|
163
|
+
cp .env.example .env
|
|
164
|
+
# Edit .env with your values
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Configuration
|
|
170
|
+
|
|
171
|
+
### Environment Variables
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
# Data Store (supabase is default; confluence is legacy)
|
|
175
|
+
DATA_STORE=supabase
|
|
176
|
+
|
|
177
|
+
# Supabase (required when DATA_STORE=supabase)
|
|
178
|
+
SUPABASE_URL=https://your-project.supabase.co
|
|
179
|
+
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
|
|
180
|
+
|
|
181
|
+
# Transport mode
|
|
182
|
+
TRANSPORT_MODE=http # or stdio for local MCP clients
|
|
183
|
+
|
|
184
|
+
# HTTP auth (required when TRANSPORT_MODE=http)
|
|
185
|
+
HTTP_PORT=3000
|
|
186
|
+
API_AUTH_TOKEN=your-secure-random-token # openssl rand -base64 32
|
|
187
|
+
|
|
188
|
+
# Logging
|
|
189
|
+
LOG_LEVEL=info # debug | info | warn | error
|
|
190
|
+
|
|
191
|
+
# RepoMix — private repo access (optional)
|
|
192
|
+
GITHUB_TOKEN=ghp_xxxx
|
|
193
|
+
GITLAB_TOKEN=glpat-xxxx
|
|
194
|
+
BITBUCKET_TOKEN=xxxx
|
|
195
|
+
|
|
196
|
+
# AWS Athena — Research & Analyze Skill (optional)
|
|
197
|
+
AWS_REGION=us-east-1
|
|
198
|
+
AWS_ACCESS_KEY_ID=xxxx
|
|
199
|
+
AWS_SECRET_ACCESS_KEY=xxxx
|
|
200
|
+
ATHENA_S3_OUTPUT_LOCATION=s3://your-bucket/athena-results/
|
|
201
|
+
ATHENA_DATABASE=default
|
|
202
|
+
ATHENA_WORKGROUP=primary
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
| Variable | Required | Description |
|
|
206
|
+
|----------|----------|-------------|
|
|
207
|
+
| `DATA_STORE` | No | `supabase` (default) or `confluence` |
|
|
208
|
+
| `SUPABASE_URL` | When `supabase` | Supabase project URL |
|
|
209
|
+
| `SUPABASE_SERVICE_ROLE_KEY` | When `supabase` | Service role key (not anon key) |
|
|
210
|
+
| `TRANSPORT_MODE` | No | `stdio` (default) or `http` |
|
|
211
|
+
| `HTTP_PORT` | No | Port for HTTP server (default: 3000) |
|
|
212
|
+
| `API_AUTH_TOKEN` | When `http` | Bearer token for authentication |
|
|
213
|
+
| `GITHUB_TOKEN` | For private repos | GitHub PAT with repo read access |
|
|
214
|
+
| `AWS_*` / `ATHENA_*` | For Research & Analyze | AWS credentials and Athena config |
|
|
215
|
+
| `ATHENA_DATABASE` | No | Athena database/catalog name (default: `"default"`); overridable per `query_data` call |
|
|
216
|
+
|
|
217
|
+
### MCP Client Configuration
|
|
218
|
+
|
|
219
|
+
#### Claude Code (CLI)
|
|
220
|
+
|
|
221
|
+
```bash
|
|
222
|
+
# Remote (recommended — or use npx codifier init)
|
|
223
|
+
claude mcp add --transport http codifier https://codifier-mcp.fly.dev/mcp \
|
|
224
|
+
--header "Authorization: Bearer <your-token>"
|
|
225
|
+
|
|
226
|
+
# Local
|
|
227
|
+
claude mcp add --transport http codifier http://localhost:3000/mcp \
|
|
228
|
+
--header "Authorization: Bearer <your-token>"
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
#### Claude Desktop
|
|
232
|
+
|
|
233
|
+
Claude Desktop requires the `mcp-remote` proxy to connect to SSE servers:
|
|
234
|
+
|
|
235
|
+
```json
|
|
236
|
+
{
|
|
237
|
+
"mcpServers": {
|
|
238
|
+
"codifier": {
|
|
239
|
+
"command": "npx",
|
|
240
|
+
"args": [
|
|
241
|
+
"-y",
|
|
242
|
+
"mcp-remote",
|
|
243
|
+
"https://codifier-mcp.fly.dev/mcp",
|
|
244
|
+
"--header",
|
|
245
|
+
"Authorization:Bearer <your-token>"
|
|
246
|
+
]
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
#### Cursor / Other MCP Clients
|
|
253
|
+
|
|
254
|
+
Configure as a StreamableHTTP server at `https://codifier-mcp.fly.dev/mcp` with `Authorization: Bearer <token>` header.
|
|
255
|
+
|
|
256
|
+
---
|
|
257
|
+
|
|
258
|
+
## MCP Tools
|
|
259
|
+
|
|
260
|
+
Codifier exposes 5 tools via the MCP protocol:
|
|
261
|
+
|
|
262
|
+
| Tool | Description |
|
|
263
|
+
|------|-------------|
|
|
264
|
+
| `fetch_context` | Retrieve memories from the KB filtered by `project_id`, `memory_type` (rule, document, api_contract, learning, research_finding), and/or `tags` |
|
|
265
|
+
| `update_memory` | Create or update a memory within the active project scope |
|
|
266
|
+
| `manage_projects` | Create, list, or switch the active project; all subsequent calls are scoped to it |
|
|
267
|
+
| `pack_repo` | Condense a local or remote repository via RepoMix and store it as a versioned snapshot in the `repositories` table |
|
|
268
|
+
| `query_data` | Execute operations against Athena: `list-tables` (schema discovery), `describe-tables` (column metadata), `execute-query` (SELECT only). Accepts optional `database` parameter to override the `ATHENA_DATABASE` env var per call. |
|
|
269
|
+
|
|
270
|
+
### Memory Types
|
|
271
|
+
|
|
272
|
+
| Type | Description |
|
|
273
|
+
|------|-------------|
|
|
274
|
+
| `rule` | Project conventions, security patterns, coding standards |
|
|
275
|
+
| `document` | Technical specs, ADRs, runbooks, best practices |
|
|
276
|
+
| `api_contract` | Endpoint specifications, schemas, auth requirements |
|
|
277
|
+
| `learning` | Insights captured during AI-assisted development |
|
|
278
|
+
| `research_finding` | Data analysis results from Research & Analyze sessions |
|
|
279
|
+
|
|
280
|
+
---
|
|
281
|
+
|
|
282
|
+
## Skills
|
|
283
|
+
|
|
284
|
+
Skills are client-side, model-agnostic Agent workflows — markdown instruction files that the LLM reads locally. The LLM drives the conversation and calls MCP tools only for data operations. There is no server-side session state or protocol round-trips between steps.
|
|
285
|
+
|
|
286
|
+
After running `npx codifier init`, Skills live in `.codifier/skills/` in your project. Slash commands in `.claude/commands/` (or the equivalent for your client) activate each Skill.
|
|
287
|
+
|
|
288
|
+
`skills/shared/codifier-tools.md` is a reference document covering all 5 MCP tools, their parameters, and usage patterns. Every Skill references it.
|
|
289
|
+
|
|
290
|
+
### Developer Skills
|
|
291
|
+
|
|
292
|
+
#### Initialize Project (`/init`)
|
|
293
|
+
|
|
294
|
+
For greenfield and brownfield projects. Produces four artifacts persisted to the shared KB.
|
|
295
|
+
|
|
296
|
+
**Workflow:** collect project name and description → optionally accept SOW → optionally provide repo URLs → pack repos via `pack_repo` → generate Rules.md → generate Evals.md → generate Requirements.md → generate Roadmap.md → persist all artifacts via `update_memory`
|
|
297
|
+
|
|
298
|
+
**Context-aware generation:**
|
|
299
|
+
|
|
300
|
+
| Scenario | Context used | Generator behavior |
|
|
301
|
+
|----------|-------------|-------------------|
|
|
302
|
+
| Greenfield + SOW | description + SOW | Rules from SOW constraints and standards |
|
|
303
|
+
| Greenfield, no SOW | description only | Minimal scaffolding rules |
|
|
304
|
+
| Brownfield + SOW | description + SOW + repo snapshot | Target-state rules; SOW takes precedence over existing patterns |
|
|
305
|
+
| Brownfield, no SOW | description + repo snapshot | Rules extracted from existing codebase patterns |
|
|
306
|
+
|
|
307
|
+
#### Brownfield Onboard (`/onboard`)
|
|
308
|
+
|
|
309
|
+
Pack an existing repo and generate an architectural summary with minimal ceremony.
|
|
310
|
+
|
|
311
|
+
**Workflow:** collect repo URLs → call `pack_repo` for each → store versioned snapshots → generate architectural summary → persist learnings via `update_memory`
|
|
312
|
+
|
|
313
|
+
### Researcher Skills
|
|
314
|
+
|
|
315
|
+
#### Research & Analyze (`/research`)
|
|
316
|
+
|
|
317
|
+
Connect to Athena, explore data, execute queries, synthesize findings.
|
|
318
|
+
|
|
319
|
+
**Workflow:** define research objective → provide context → discover Athena schema via `query_data list-tables` → select relevant tables → describe schemas via `query_data describe-tables` → generate SQL queries (user reviews before execution) → execute approved queries via `query_data execute-query` → synthesize findings → generate ResearchFindings.md → persist as `research_finding` memories via `update_memory`
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Remote Server (HTTP Mode)
|
|
324
|
+
|
|
325
|
+
### Quick Start
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
# Generate auth token
|
|
329
|
+
export API_AUTH_TOKEN=$(openssl rand -base64 32)
|
|
330
|
+
|
|
331
|
+
# Start in HTTP mode
|
|
332
|
+
TRANSPORT_MODE=http \
|
|
333
|
+
HTTP_PORT=3000 \
|
|
334
|
+
API_AUTH_TOKEN=$API_AUTH_TOKEN \
|
|
335
|
+
SUPABASE_URL=https://your-project.supabase.co \
|
|
336
|
+
SUPABASE_SERVICE_ROLE_KEY=your-key \
|
|
337
|
+
node dist/index.js
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
### Endpoints
|
|
341
|
+
|
|
342
|
+
| Endpoint | Methods | Auth | Description |
|
|
343
|
+
|----------|---------|------|-------------|
|
|
344
|
+
| `/health` | GET | No | Health check — returns `{"status":"ok"}` |
|
|
345
|
+
| `/.well-known/oauth-authorization-server` | GET | No | OAuth authorization server metadata (MCP SDK 1.7+ discovery) |
|
|
346
|
+
| `/.well-known/oauth-protected-resource` | GET | No | OAuth protected resource metadata |
|
|
347
|
+
| `/mcp` | POST | Yes | StreamableHTTP transport — stateless (MCP protocol 2025-03-26); GET/DELETE return 405 |
|
|
348
|
+
| `/sse` | GET | Yes | SSE transport for legacy clients |
|
|
349
|
+
| `/messages` | POST | Yes | SSE message endpoint |
|
|
350
|
+
|
|
351
|
+
### Authentication
|
|
352
|
+
|
|
353
|
+
All endpoints except `/health`, `/.well-known/*`, and `OPTIONS` preflight requests require:
|
|
354
|
+
```
|
|
355
|
+
Authorization: Bearer <API_AUTH_TOKEN>
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Requests without a valid token receive a `401` response with an OAuth-standard error body:
|
|
359
|
+
```json
|
|
360
|
+
{ "error": "unauthorized", "error_description": "..." }
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## Development
|
|
366
|
+
|
|
367
|
+
### Project Structure
|
|
368
|
+
|
|
369
|
+
```
|
|
370
|
+
codifierMcp/
|
|
371
|
+
├── src/
|
|
372
|
+
│ ├── index.ts # Entry point (transport branching)
|
|
373
|
+
│ ├── config/
|
|
374
|
+
│ │ └── env.ts # Zod-validated configuration
|
|
375
|
+
│ ├── http/
|
|
376
|
+
│ │ ├── server.ts # Express server (StreamableHTTP + SSE)
|
|
377
|
+
│ │ └── auth-middleware.ts # Bearer token authentication
|
|
378
|
+
│ ├── datastore/
|
|
379
|
+
│ │ ├── interface.ts # IDataStore abstraction
|
|
380
|
+
│ │ ├── factory.ts # createDataStore() factory
|
|
381
|
+
│ │ ├── supabase-datastore.ts # Supabase implementation (default)
|
|
382
|
+
│ │ └── atlassian-datastore.ts # Confluence implementation (legacy)
|
|
383
|
+
│ ├── mcp/
|
|
384
|
+
│ │ ├── server.ts # Registers exactly 5 tools
|
|
385
|
+
│ │ ├── schemas.ts # Zod schemas for tool parameters
|
|
386
|
+
│ │ └── tools/ # 5 tool implementations
|
|
387
|
+
│ │ ├── fetch-context.ts
|
|
388
|
+
│ │ ├── update-memory.ts
|
|
389
|
+
│ │ ├── manage-projects.ts
|
|
390
|
+
│ │ ├── pack-repo.ts
|
|
391
|
+
│ │ └── query-data.ts
|
|
392
|
+
│ ├── integrations/
|
|
393
|
+
│ │ ├── repomix.ts # RepoMix programmatic API wrapper
|
|
394
|
+
│ │ └── athena.ts # Athena MCP sidecar client
|
|
395
|
+
│ ├── services/
|
|
396
|
+
│ │ ├── context-service.ts # Rule retrieval with relevance scoring
|
|
397
|
+
│ │ └── memory-service.ts # Memory enrichment and storage
|
|
398
|
+
│ └── utils/
|
|
399
|
+
│ ├── logger.ts # Logging (stderr only)
|
|
400
|
+
│ └── errors.ts # Custom error classes
|
|
401
|
+
├── skills/
|
|
402
|
+
│ ├── shared/
|
|
403
|
+
│ │ └── codifier-tools.md # All 5 MCP tools reference
|
|
404
|
+
│ ├── initialize-project/
|
|
405
|
+
│ │ ├── SKILL.md
|
|
406
|
+
│ │ └── templates/
|
|
407
|
+
│ ├── brownfield-onboard/
|
|
408
|
+
│ │ └── SKILL.md
|
|
409
|
+
│ └── research-analyze/
|
|
410
|
+
│ ├── SKILL.md
|
|
411
|
+
│ └── templates/
|
|
412
|
+
├── commands/
|
|
413
|
+
│ ├── init.md # /init slash command
|
|
414
|
+
│ ├── onboard.md # /onboard slash command
|
|
415
|
+
│ └── research.md # /research slash command
|
|
416
|
+
├── cli/
|
|
417
|
+
│ ├── bin/codifier.ts # CLI entry point
|
|
418
|
+
│ ├── detect.ts # LLM client detection
|
|
419
|
+
│ ├── init.ts # npx codifier init
|
|
420
|
+
│ ├── update.ts # npx codifier update
|
|
421
|
+
│ ├── add.ts # npx codifier add <skill>
|
|
422
|
+
│ └── doctor.ts # npx codifier doctor
|
|
423
|
+
├── supabase/
|
|
424
|
+
│ └── migrations/
|
|
425
|
+
│ ├── 001_initial_schema.sql
|
|
426
|
+
│ └── 002_v2_schema.sql # Drops sessions/insights; v2.0 schema
|
|
427
|
+
├── docs/
|
|
428
|
+
│ ├── rules.yaml # Project development rules
|
|
429
|
+
│ └── evals.yaml # Rule evaluations
|
|
430
|
+
├── Dockerfile
|
|
431
|
+
├── fly.toml
|
|
432
|
+
└── package.json
|
|
433
|
+
```
|
|
434
|
+
|
|
435
|
+
### Commands
|
|
436
|
+
|
|
437
|
+
```bash
|
|
438
|
+
npm install # Install dependencies
|
|
439
|
+
npm run build # Compile TypeScript → dist/
|
|
440
|
+
npm run dev # Build + run (stdio mode)
|
|
441
|
+
npm run watch # Watch mode (rebuild on changes)
|
|
442
|
+
```
|
|
443
|
+
|
|
444
|
+
### Adding New Features
|
|
445
|
+
|
|
446
|
+
1. Review `docs/rules.yaml` before writing code
|
|
447
|
+
2. Follow the `IDataStore` interface for any storage changes
|
|
448
|
+
3. Use custom error classes from `utils/errors.ts`
|
|
449
|
+
4. Log to stderr only (never stdout) — MCP uses stdout for protocol
|
|
450
|
+
5. Validate all inputs with Zod schemas in `src/mcp/schemas.ts`
|
|
451
|
+
6. Use strict TypeScript; explicit types required
|
|
452
|
+
|
|
453
|
+
---
|
|
454
|
+
|
|
455
|
+
## Architecture Details
|
|
456
|
+
|
|
457
|
+
### Data Schema
|
|
458
|
+
|
|
459
|
+
Migration `002_v2_schema.sql` (applied 2026-02-24) dropped the `sessions` and `insights` tables. The active schema has 4 tables:
|
|
460
|
+
|
|
461
|
+
| Table | Key Fields | Purpose |
|
|
462
|
+
|-------|-----------|---------|
|
|
463
|
+
| `projects` | id, name, org, metadata | Top-level container; all entities scoped to a project |
|
|
464
|
+
| `repositories` | id, project_id, url, snapshot, file_tree, version_label | Versioned repo snapshots from RepoMix |
|
|
465
|
+
| `memories` | id, project_id, memory_type, title, content, tags, confidence, embedding, source_role | All knowledge entities (rules, docs, learnings, findings) |
|
|
466
|
+
| `api_keys` | id, project_id, key_hash | API key → project mapping for RLS |
|
|
467
|
+
|
|
468
|
+
### Retrieval Strategy
|
|
469
|
+
|
|
470
|
+
**MVP**: Exact-match filtering on `project_id`, `memory_type`, and `tags`. Embeddings are stored on write but vector similarity search is deferred to v2.1.
|
|
471
|
+
|
|
472
|
+
**v2.1**: Hybrid retrieval — exact-match filters + vector ranking via pgvector.
|
|
473
|
+
|
|
474
|
+
### Why Skills Instead of a Server-Side PlaybookRunner
|
|
475
|
+
|
|
476
|
+
The original v2.0 design used a server-side `PlaybookRunner` state machine with a `sessions` table, `run_playbook`, and `advance_step` tools. This was replaced in February 2026 for three reasons:
|
|
477
|
+
|
|
478
|
+
1. **Eliminating round-trips**: Each playbook step required an MCP call. Skills let the LLM manage workflow state in its context window — zero extra tool calls for step transitions.
|
|
479
|
+
2. **Model agnosticism**: Skill markdown files work with any LLM client. The YAML playbook format tied generation to Codifier's server-side prompt assembly.
|
|
480
|
+
3. **Simplified server**: 5 stateless tools are easier to reason about, test, and scale. The Fly.io deployment runs always-on (`min_machines_running = 1`, `auto_stop_machines = false`) — no cold-start delay for clients.
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## Roadmap
|
|
485
|
+
|
|
486
|
+
### v2.1
|
|
487
|
+
|
|
488
|
+
| Feature | Description |
|
|
489
|
+
|---------|-------------|
|
|
490
|
+
| **Semantic search** | Activate vector similarity on `memories.embedding`; hybrid retrieval |
|
|
491
|
+
| **SkillManager / Umbrella MCP** | Proxy pattern for Confluence, SharePoint, GitHub, Jira connectors |
|
|
492
|
+
| **Researcher data sources** | SharePoint + Google Drive as selectable sources in Research & Analyze |
|
|
493
|
+
| **Architect Skills** | Technology evaluation, system modeling, ADRs |
|
|
494
|
+
| **Strategist Skills** | Roadmap planning, competitive analysis |
|
|
495
|
+
| **Teams bot** | Read-only KB queries + Skill steps as Adaptive Cards |
|
|
496
|
+
| **SSO / Entra ID** | Replace API key auth with org SSO |
|
|
497
|
+
| **Memory relationships** | Graph edges between memories for relationship queries |
|
|
498
|
+
|
|
499
|
+
---
|
|
500
|
+
|
|
501
|
+
## Additional Resources
|
|
502
|
+
|
|
503
|
+
- **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
|
|
504
|
+
- **Supabase**: [supabase.com/docs](https://supabase.com/docs)
|
|
505
|
+
- **RepoMix**: [github.com/yamadashy/repomix](https://github.com/yamadashy/repomix)
|
|
506
|
+
- **AWS Athena MCP**: [github.com/ColeMurray/aws-athena-mcp](https://github.com/ColeMurray/aws-athena-mcp)
|
|
507
|
+
- **TypeScript Handbook**: [typescriptlang.org/docs](https://www.typescriptlang.org/docs/)
|
|
508
|
+
|
|
509
|
+
---
|
|
510
|
+
|
|
511
|
+
**Built with Claude Code**
|
package/commands/init.md
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
Read and follow the instructions in .codifier/skills/initialize-project/SKILL.md. Use the Codifier MCP tools as directed by the skill.
|
|
2
|
+
|
|
3
|
+
If the skill file is not found at .codifier/skills/initialize-project/SKILL.md, inform the user: "Codifier skills are not installed yet. Run `npx codifier init` in your terminal to install them, then try this command again."
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
Read and follow the instructions in .codifier/skills/brownfield-onboard/SKILL.md. Use the Codifier MCP tools as directed by the skill.
|
|
2
|
+
|
|
3
|
+
If the skill file is not found at .codifier/skills/brownfield-onboard/SKILL.md, inform the user: "Codifier skills are not installed yet. Run `npx codifier init` in your terminal to install them, then try this command again."
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
Read and follow the instructions in .codifier/skills/research-analyze/SKILL.md. Use the Codifier MCP tools as directed by the skill.
|
|
2
|
+
|
|
3
|
+
If the skill file is not found at .codifier/skills/research-analyze/SKILL.md, inform the user: "Codifier skills are not installed yet. Run `npx codifier init` in your terminal to install them, then try this command again."
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../cli/add.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,wBAAsB,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe7D"}
|
package/dist/cli/add.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `codifier add <skill>` — install a single skill by name.
|
|
3
|
+
*/
|
|
4
|
+
import { cpSync, existsSync, mkdirSync } from 'fs';
|
|
5
|
+
import { join, dirname } from 'path';
|
|
6
|
+
import { fileURLToPath } from 'url';
|
|
7
|
+
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
8
|
+
const PACKAGE_ROOT = join(__dirname, '..', '..');
|
|
9
|
+
const SKILLS_SOURCE = join(PACKAGE_ROOT, 'skills');
|
|
10
|
+
export async function runAdd(skillName) {
|
|
11
|
+
const cwd = process.cwd();
|
|
12
|
+
const skillSource = join(SKILLS_SOURCE, skillName);
|
|
13
|
+
if (!existsSync(skillSource)) {
|
|
14
|
+
console.error(`Error: Skill "${skillName}" not found.`);
|
|
15
|
+
console.error('Available skills: initialize-project, brownfield-onboard, research-analyze');
|
|
16
|
+
process.exit(1);
|
|
17
|
+
}
|
|
18
|
+
const skillsDest = join(cwd, '.codifier', 'skills', skillName);
|
|
19
|
+
mkdirSync(skillsDest, { recursive: true });
|
|
20
|
+
cpSync(skillSource, skillsDest, { recursive: true });
|
|
21
|
+
console.log(`✓ Skill "${skillName}" installed to .codifier/skills/${skillName}/`);
|
|
22
|
+
}
|
|
23
|
+
//# sourceMappingURL=add.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"add.js","sourceRoot":"","sources":["../../cli/add.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AACjD,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AAEnD,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,SAAiB;IAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAC1B,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAEnD,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,iBAAiB,SAAS,cAAc,CAAC,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,4EAA4E,CAAC,CAAC;QAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/D,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,CAAC,WAAW,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAErD,OAAO,CAAC,GAAG,CAAC,YAAY,SAAS,mCAAmC,SAAS,GAAG,CAAC,CAAC;AACpF,CAAC"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codifier.d.ts","sourceRoot":"","sources":["../../../cli/bin/codifier.ts"],"names":[],"mappings":";AACA;;;GAGG"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Codifier CLI entry point
|
|
4
|
+
* Usage: npx codifier <command>
|
|
5
|
+
*/
|
|
6
|
+
import { program } from 'commander';
|
|
7
|
+
import { runInit } from '../init.js';
|
|
8
|
+
import { runUpdate } from '../update.js';
|
|
9
|
+
import { runAdd } from '../add.js';
|
|
10
|
+
import { runDoctor } from '../doctor.js';
|
|
11
|
+
program
|
|
12
|
+
.name('codifier')
|
|
13
|
+
.description('Codifier MCP — install and manage AI skills for your project')
|
|
14
|
+
.version('2.0.0');
|
|
15
|
+
program
|
|
16
|
+
.command('init')
|
|
17
|
+
.description('Scaffold Codifier skills, slash commands, and MCP config into this project')
|
|
18
|
+
.action(async () => {
|
|
19
|
+
await runInit();
|
|
20
|
+
});
|
|
21
|
+
program
|
|
22
|
+
.command('update')
|
|
23
|
+
.description('Pull the latest skills from the npm package into .codifier/skills/')
|
|
24
|
+
.action(async () => {
|
|
25
|
+
await runUpdate();
|
|
26
|
+
});
|
|
27
|
+
program
|
|
28
|
+
.command('add <skill>')
|
|
29
|
+
.description('Install a single skill by name (e.g., research-analyze)')
|
|
30
|
+
.action(async (skill) => {
|
|
31
|
+
await runAdd(skill);
|
|
32
|
+
});
|
|
33
|
+
program
|
|
34
|
+
.command('doctor')
|
|
35
|
+
.description('Verify MCP connectivity and check installed skill files')
|
|
36
|
+
.action(async () => {
|
|
37
|
+
await runDoctor();
|
|
38
|
+
});
|
|
39
|
+
program.parseAsync(process.argv).catch((err) => {
|
|
40
|
+
console.error('Error:', err.message);
|
|
41
|
+
process.exit(1);
|
|
42
|
+
});
|
|
43
|
+
//# sourceMappingURL=codifier.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"codifier.js","sourceRoot":"","sources":["../../../cli/bin/codifier.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,8DAA8D,CAAC;KAC3E,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,4EAA4E,CAAC;KACzF,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,OAAO,EAAE,CAAC;AAClB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,oEAAoE,CAAC;KACjF,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,SAAS,EAAE,CAAC;AACpB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,aAAa,CAAC;KACtB,WAAW,CAAC,yDAAyD,CAAC;KACtE,MAAM,CAAC,KAAK,EAAE,KAAa,EAAE,EAAE;IAC9B,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;AACtB,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,yDAAyD,CAAC;KACtE,MAAM,CAAC,KAAK,IAAI,EAAE;IACjB,MAAM,SAAS,EAAE,CAAC;AACpB,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAU,EAAE,EAAE;IACpD,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Environment detection — identifies which LLM client is in use
|
|
3
|
+
* by checking for client-specific directories.
|
|
4
|
+
*/
|
|
5
|
+
export type ClientType = 'claude-code' | 'cursor' | 'windsurf' | 'generic';
|
|
6
|
+
export interface DetectedEnvironment {
|
|
7
|
+
clientType: ClientType;
|
|
8
|
+
commandsDir: string;
|
|
9
|
+
mcpConfigPath: string;
|
|
10
|
+
}
|
|
11
|
+
export declare function detectEnvironment(cwd?: string): DetectedEnvironment;
|
|
12
|
+
//# sourceMappingURL=detect.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../cli/detect.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,MAAM,MAAM,UAAU,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3E,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,mBAAmB,CA8BlF"}
|