Skip to content

Commit 99801e7

Browse files
DevRohit06claude
DevRohit06
and
claude
committed
Initial release: Lito Graph compiler, MCP server, CLI, and docs
- Graph compiler: Markdown → typed knowledge graph (graph.json) - 5 node types: doc, concept, api, workflow, step - 14 edge types: structural, semantic, capability, procedural - Zod-validated frontmatter schemas per doc type - Backward compatible with existing Lito `api: "GET /endpoint"` format - Deterministic node IDs (SHA-256 hash of source_path:type) - MCP server: 7 tools over stdio transport - list_nodes, get_node, traverse, search - get_workflow, find_apis_for_entity, get_graph_stats - Resources: full graph + individual nodes - CLI: build, serve, inspect commands - @clack/prompts interactive UI matching Lito CLI patterns - Docs: self-referential Lito-format documentation (18 pages) - Compiles into its own graph (35 nodes, 56 edges) - GitHub Pages deployment via GitHub Actions - Tests: 30 tests (unit + integration), all passing Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
0 parents  commit 99801e7

60 files changed

Lines changed: 4642 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Deploy Docs
2+
on:
3+
push:
4+
branches: [main]
5+
pull_request:
6+
branches: [main]
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Setup Node.js
25+
uses: actions/setup-node@v4
26+
with:
27+
node-version: 20
28+
29+
- name: Build docs site
30+
run: npx --yes @litodocs/cli build -i ./docs
31+
32+
- name: Upload artifact
33+
uses: actions/upload-pages-artifact@v3
34+
with:
35+
path: ./dist
36+
37+
deploy:
38+
environment:
39+
name: github-pages
40+
url: ${{ steps.deployment.outputs.page_url }}
41+
runs-on: ubuntu-latest
42+
needs: build
43+
if: github.ref == 'refs/heads/main'
44+
steps:
45+
- name: Deploy to GitHub Pages
46+
id: deployment
47+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules/
2+
dist/
3+
*.tsbuildinfo
4+
graph.json
5+
.DS_Store

‎README.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Lito Graph
2+
3+
Compile Markdown docs into a knowledge & workflow graph for AI agents. Expose it via MCP so IDEs and assistants can reason, plan, and act over your documentation — not just search it.
4+
5+
Part of the [Lito](https://github.com/Lito-docs/cli) documentation ecosystem.
6+
7+
## Why
8+
9+
Traditional docs are flat text optimized for human reading. AI agents need **structured, traversable knowledge** to:
10+
11+
- **Discover** capabilities — "What APIs act on the Workspace entity?"
12+
- **Plan** multi-step tasks — "Walk me through the onboarding workflow, step by step"
13+
- **Stay safe** — "Does this workflow require human approval? What are the guardrails?"
14+
15+
Lito Graph compiles your Markdown into a typed knowledge graph with nodes (concepts, APIs, workflows, steps) and edges (ACTS_ON, USES_API, NEXT_STEP_OF, etc.), then serves it over MCP.
16+
17+
## Quick Start
18+
19+
```bash
20+
# Install
21+
cd lito-graph
22+
bun install
23+
24+
# Build a graph from your docs
25+
bun run bin/cli.ts build -i ../docs -o ./graph.json
26+
27+
# Inspect it
28+
bun run bin/cli.ts inspect -g ./graph.json --stats
29+
30+
# Start MCP server
31+
bun run bin/cli.ts serve -g ./graph.json
32+
```
33+
34+
## Document Types
35+
36+
Add `type` to your Markdown frontmatter to create rich graph nodes:
37+
38+
### Concept Docs
39+
40+
```yaml
41+
---
42+
type: concept
43+
canonical_name: "Workspace"
44+
entity_type: "resource"
45+
aliases: ["Org Workspace"]
46+
related_entities: ["User", "Project"]
47+
---
48+
```
49+
50+
### API Docs
51+
52+
```yaml
53+
---
54+
type: api
55+
operation_id: "create_workspace"
56+
method: "POST"
57+
path: "/v1/workspaces"
58+
resource: "Workspace"
59+
capabilities: ["create"]
60+
preconditions: ["user_authenticated"]
61+
permissions: ["workspace:write"]
62+
---
63+
```
64+
65+
### Workflow Docs
66+
67+
```yaml
68+
---
69+
type: workflow
70+
workflow_id: "onboard_new_workspace"
71+
goal: "Onboard a new customer workspace."
72+
risk_level: "medium"
73+
requires_human_approval: true
74+
---
75+
```
76+
77+
Existing Lito API docs (`api: "GET /users"`) are auto-converted — no migration needed.
78+
79+
## CLI Commands
80+
81+
| Command | Description |
82+
|---------|-------------|
83+
| `lito-graph build -i ./docs -o ./graph.json` | Compile docs into graph |
84+
| `lito-graph serve -g ./graph.json` | Start MCP server on stdio |
85+
| `lito-graph serve -i ./docs` | Build + serve in one step |
86+
| `lito-graph inspect -g ./graph.json --stats` | Graph overview |
87+
| `lito-graph inspect -g ./graph.json --nodes` | List all nodes |
88+
| `lito-graph inspect -g ./graph.json --orphans` | Find disconnected nodes |
89+
| `lito-graph inspect -g ./graph.json --unresolved` | Show broken references |
90+
91+
## MCP Tools
92+
93+
The server exposes 7 tools for agents:
94+
95+
| Tool | Description |
96+
|------|-------------|
97+
| `list_nodes` | Filter nodes by type or tag |
98+
| `get_node` | Full details by ID or slug |
99+
| `traverse` | Walk edges from a node |
100+
| `search` | Keyword search across the graph |
101+
| `get_workflow` | Complete workflow with steps + linked APIs |
102+
| `find_apis_for_entity` | All APIs acting on an entity |
103+
| `get_graph_stats` | Overview statistics |
104+
105+
## IDE Setup
106+
107+
### Claude Code
108+
109+
Add to `.mcp.json` in your project root:
110+
111+
```json
112+
{
113+
"mcpServers": {
114+
"lito-graph": {
115+
"type": "stdio",
116+
"command": "bun",
117+
"args": ["run", "path/to/lito-graph/bin/cli.ts", "serve", "-g", "./graph.json"]
118+
}
119+
}
120+
}
121+
```
122+
123+
### Claude Desktop / Cursor
124+
125+
Add to your MCP settings:
126+
127+
```json
128+
{
129+
"mcpServers": {
130+
"lito-graph": {
131+
"command": "bun",
132+
"args": ["run", "path/to/lito-graph/bin/cli.ts", "serve", "-g", "./graph.json"]
133+
}
134+
}
135+
}
136+
```
137+
138+
## Graph Data Model
139+
140+
### Node Types
141+
142+
- **DocNode** — standard documentation pages
143+
- **ConceptNode** — domain entities (Workspace, User, Project)
144+
- **ApiNode** — callable capabilities (HTTP endpoints, functions)
145+
- **WorkflowNode** — multi-step procedures with guardrails
146+
- **StepNode** — individual actions within workflows
147+
148+
### Edge Types
149+
150+
- **Structural:** PARENT_OF, CHILD_OF, NEXT_SECTION
151+
- **Semantic:** RELATED_TO, DEPENDS_ON, CONTAINS, DEPRECATED_BY
152+
- **Capability:** ACTS_ON, REQUIRES, EMITS, USES_API
153+
- **Procedural:** NEXT_STEP_OF, ON_FAILURE_TRIGGER, ESCALATES_TO
154+
155+
## License
156+
157+
MIT

‎bin/cli.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#!/usr/bin/env bun
2+
import { cli } from "../src/cli.js";
3+
4+
cli();

0 commit comments

Comments
 (0)