Skip to content

Commit 8571b5b

Browse files
JaysonGCSJaysonGCS
authored
feat(asc-viewer-cli): add MCP server for AI assistant integration (#68)
* feat(asc-viewer-cli): add MCP server for AI assistant integration Add Model Context Protocol (MCP) support to asc-viewer-cli, enabling AI assistants to analyze Recoil state and launch visualizations. New MCP tools: - analyze_state: Generate dependency graph from entry file/variable - find_cycles: Detect cyclic dependencies and self-references - list_atoms: List all atoms/selectors in a file with dependencies - launch_viewer: Start the visualization server Changes: - Add mcp subcommand to CLI (asc-viewer mcp) - Refactor CLI to use Commander.js with subcommands - Add @modelcontextprotocol/sdk, zod, zod-to-json-schema dependencies - Update documentation with MCP setup and configuration options * fix * feat: update zod to v4 and remove zod-to-json-schema * feat: update tool
1 parent 1c913c1 commit 8571b5b

10 files changed

Lines changed: 1098 additions & 219 deletions

File tree

‎CLAUDE.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Build and Development Commands
6+
7+
```bash
8+
# Build
9+
npm run build # Build asc-cli
10+
npm run build:all # Build all apps (asc-cli, asc-viewer, asc-viewer-cli)
11+
npm run build:viewer-cli # Build asc-viewer and asc-viewer-cli together
12+
13+
# Development
14+
npm run viewer:dev # Run asc-viewer dev server
15+
npm run viewer-cli:dev # Run asc-viewer-cli in dev mode (uses --dev flag)
16+
npm run build:watch # Watch mode for asc-cli
17+
npx nx mcp asc-viewer-cli # Run MCP server in dev mode
18+
19+
# Test
20+
npm run test # Run all tests once
21+
npm run test:watch # Run tests in watch mode
22+
npm run test:ui # Run tests with Vitest UI
23+
24+
# Lint
25+
npm run lint # Run ESLint on all projects
26+
27+
# Release
28+
npm run release-all:dry-run # Dry run multi-package semantic release
29+
npm run release-all # Release all packages
30+
```
31+
32+
## Project Structure
33+
34+
This is an Nx monorepo with three main applications and two library packages:
35+
36+
### Apps
37+
- **asc-cli** (`apps/asc-cli`): CLI that generates JSON Canvas files for Recoil state visualization. Entry: `atomic-state-canvas` command.
38+
- **asc-viewer** (`apps/asc-viewer`): React web app for 2D/3D visualization using react-force-graph. Uses Jotai for state, Tailwind for styling.
39+
- **asc-viewer-cli** (`apps/asc-viewer-cli`): CLI that starts a Vite dev server, watches `.asc.` files, and serves the viewer. Also includes MCP server for AI assistant integration. Entry: `asc-viewer` command with subcommands `serve` (default) and `mcp`.
40+
41+
### Libs
42+
- **core** (`libs/core`): Core parsing and graph logic - AST parsing with oxc-parser, graph data structures, layout algorithms, cycle detection.
43+
- **asc-viewer-libs** (`libs/asc-viewer-libs`): Shared types and utilities for the viewer.
44+
45+
## Architecture
46+
47+
### Core Parsing Flow (`libs/core`)
48+
1. **graphUtils.ts**: Reads files, parses AST with oxc-parser, walks with acorn-walk to extract imports and Recoil declarations
49+
2. **plugins/recoil.ts**: Plugin that identifies `atom`, `selector`, `atomFamily`, `selectorFamily` calls and extracts dependencies from `get()` calls
50+
3. **core.ts**: `generateAtomicStateGraph()` builds a dependency graph from an entry file/variable
51+
4. **dataStructure.ts**: `Graph` class maintains adjacency list, edge map, and generates level topology for layout
52+
5. **cycleDetection/index.ts**: DFS-based cycle detection for self-references and cyclic dependencies
53+
6. **graphLayout/**: Two layout algorithms - `SIMPLE_TOPOLOGY` (level-based) and `FORCE_DIRECTED` (d3-force)
54+
55+
### asc-viewer-cli Flow
56+
1. Loads config via cosmiconfig (`.ascrc`, `asc.config.js`, etc.)
57+
2. Uses chokidar to watch for `.asc.` files
58+
3. Generates metadata JSON files in `.atomic-state-canvas/` directory
59+
4. Starts Vite server with custom middleware to serve metadata at `/.atomic-state-canvas`
60+
61+
### MCP Server (`apps/asc-viewer-cli/src/mcp/`)
62+
The MCP server enables AI assistants to interact with the codebase analysis tools:
63+
- **index.ts**: Server setup using `@modelcontextprotocol/sdk` with stdio transport
64+
- **tools.ts**: Defines 4 MCP tools (`analyze_state`, `find_cycles`, `list_atoms`, `launch_viewer`) with Zod schemas
65+
- **viewer.ts**: Extracted viewer launcher logic for reuse by both CLI and MCP
66+
67+
### Plugin System
68+
The `TPluginConfig` interface in `libs/core/src/types.ts` defines how to parse AST nodes for different state libraries. Currently only Recoil is implemented via `libs/core/src/plugins/recoil.ts`.
69+
70+
## Key Patterns
71+
72+
- Uses oxc-parser for fast TypeScript/JavaScript parsing
73+
- Uses acorn-walk for AST traversal (with mock handlers for TS-specific nodes like `TSAsExpression`)
74+
- Graph output follows [JSON Canvas](https://jsoncanvas.org/) spec for Obsidian compatibility
75+
- Config uses cosmiconfig pattern: `.ascrc.json`, `asc.config.js`, `asc.config.ts`

‎README.md‎

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,32 @@ This is a mono-repository that contains a collection of applications for analyzi
66
| Application | Description | Installation |
77
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
88
| [asc-cli](./apps/asc-cli) | CLI tool for visualizing atomic state relationships. It visualizes atomic state relationships using [JSON Canvas](https://jsoncanvas.org/) | npm install @atomic-state-canvas/asc-cli -g |
9-
| [asc-viewer-cli](./apps/asc-viewer-cli) | An interactive web application for analyzing and visualizing atomic state relationships. By launching the development tool, it looks for ".asc." files in the directory and automatically populates the atomic graphs in a "Storybook"-like experience. | npm install @atomic-state-canvas/asc-viewer-cli -D |
9+
| [asc-viewer-cli](./apps/asc-viewer-cli) | An interactive web application for analyzing and visualizing atomic state relationships. By launching the development tool, it looks for ".asc." files in the directory and automatically populates the atomic graphs in a "Storybook"-like experience. Also includes MCP server for AI assistant integration. | npm install @atomic-state-canvas/asc-viewer-cli -D |
10+
11+
## Configuration (asc-viewer-cli)
12+
13+
The viewer CLI uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) for configuration. Create a config file in your project root:
14+
15+
**Supported files:** `.ascrc.json`, `.ascrc.js`, `.ascrc.yaml`, `asc.config.js`, `asc.config.ts`
16+
17+
### Options
18+
19+
| Option | Type | Default | Description |
20+
|--------|------|---------|-------------|
21+
| `watchDir` | `string` | `"src"` | Directory to watch for `.asc.` files |
22+
| `port` | `number` | `1296` | Port to run the viewer server on |
23+
| `extensions` | `string[]` | `[".asc.js", ".asc.ts"]` | File extensions to watch |
24+
| `excludePatternInGlob` | `string` | `undefined` | Glob pattern to exclude files |
25+
26+
### Example `.ascrc.json`
27+
```json
28+
{
29+
"watchDir": "./src",
30+
"port": 3000,
31+
"extensions": [".asc.ts"],
32+
"excludePatternInGlob": "*.test.ts"
33+
}
34+
```
1035

1136
## Use Cases
1237

@@ -26,6 +51,33 @@ Visualize atomic state relationships in 2D.
2651
Visualize atomic state relationships in 3D.
2752
![asc viewer - 3d](./assets/asc-viewer-3d.png)
2853

54+
## MCP Server (AI Assistant Integration)
55+
56+
The `asc-viewer-cli` includes an MCP (Model Context Protocol) server that enables AI assistants like Claude to analyze your Recoil state and launch visualizations.
57+
58+
### Setup
59+
60+
Add to your Claude Code config (`.mcp.json`):
61+
```json
62+
{
63+
"mcpServers": {
64+
"atomic-state-canvas": {
65+
"command": "npx",
66+
"args": ["@atomic-state-canvas/asc-viewer-cli", "mcp"]
67+
}
68+
}
69+
}
70+
```
71+
72+
### Available MCP Tools
73+
74+
| Tool | Description |
75+
|------|-------------|
76+
| `analyze_state` | Generate dependency graph from entry file/variable |
77+
| `find_cycles` | Detect cyclic dependencies and self-references |
78+
| `list_atoms` | List all atoms/selectors in a file with dependencies |
79+
| `launch_viewer` | Get command instructions to start the visualization server |
80+
2981
## Roadmap
3082
- [ ] Support more state management libraries such as [Jotai](https://jotai.org/)
3183
- [ ] Add support for more features in JSON Canvas such as grouping

‎apps/asc-viewer-cli/README.md‎

Lines changed: 86 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,91 @@ An interactive web application for analyzing and visualizing atomic state relati
55
## Installation
66
```bash
77
npm install @atomic-state-canvas/asc-viewer-cli -D
8+
```
9+
10+
## Configuration
11+
12+
The CLI uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) for configuration. Create one of the following files in your project root:
13+
14+
- `.ascrc.json`
15+
- `.ascrc.js`
16+
- `.ascrc.yaml`
17+
- `asc.config.js`
18+
- `asc.config.ts`
19+
20+
### Configuration Options
21+
22+
| Option | Type | Default | Description |
23+
|--------|------|---------|-------------|
24+
| `watchDir` | `string` | `"src"` | Directory to watch for `.asc.` files |
25+
| `port` | `number` | `1296` | Port to run the viewer server on |
26+
| `extensions` | `string[]` | `[".asc.js", ".asc.ts"]` | File extensions to watch |
27+
| `excludePatternInGlob` | `string` | `undefined` | Glob pattern to exclude files |
28+
29+
### Example Configuration
30+
31+
`.ascrc.json`:
32+
```json
33+
{
34+
"watchDir": "./src",
35+
"port": 3000,
36+
"extensions": [".asc.ts"],
37+
"excludePatternInGlob": "*.test.ts"
38+
}
39+
```
40+
41+
`asc.config.js`:
42+
```js
43+
module.exports = {
44+
watchDir: './src/stores',
45+
port: 1296,
46+
extensions: ['.asc.ts', '.asc.js'],
47+
excludePatternInGlob: '**/*.test.*'
48+
};
49+
```
50+
51+
## Usage
52+
53+
### Start the Viewer
54+
```bash
55+
# Start the viewer (default command)
56+
npx asc-viewer
57+
58+
# With options
59+
npx asc-viewer serve --port 3000 --watch-dir ./src
60+
```
61+
62+
### MCP Server (AI Assistant Integration)
63+
64+
Start the MCP server for AI assistant integration:
65+
```bash
66+
npx asc-viewer mcp
67+
```
868

9-
# Start the viewer
10-
npx asc-viewer-cli
69+
Add to your Claude Code config (`.mcp.json`):
70+
```json
71+
{
72+
"mcpServers": {
73+
"atomic-state-canvas": {
74+
"command": "npx",
75+
"args": ["@atomic-state-canvas/asc-viewer-cli", "mcp"]
76+
}
77+
}
78+
}
79+
```
80+
81+
#### Available MCP Tools
82+
83+
| Tool | Description |
84+
|------|-------------|
85+
| `analyze_state` | Generate dependency graph from entry file/variable |
86+
| `find_cycles` | Detect cyclic dependencies and self-references |
87+
| `list_atoms` | List all atoms/selectors in a file with dependencies |
88+
| `launch_viewer` | Get command instructions to start the visualization server |
89+
90+
#### MCP Inspector
91+
92+
Start the MCP inspector for debugging and visualization:
93+
```bash
94+
npx @modelcontextprotocol/inspector node dist/asc-viewer-cli/index.js mcp
1195
```

‎apps/asc-viewer-cli/project.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,13 @@
4343
"command": "tsx apps/asc-viewer-cli/src/index.ts --dev",
4444
"cwd": "."
4545
}
46+
},
47+
"mcp": {
48+
"executor": "nx:run-commands",
49+
"options": {
50+
"command": "tsx apps/asc-viewer-cli/src/index.ts mcp",
51+
"cwd": "."
52+
}
4653
}
4754
}
4855
}

0 commit comments

Comments
 (0)