Skip to content

Commit 1f385ba

Browse files
magicdrivemagicdrive
authored
Merge pull request #6 from magicdrive/feature/mcp_server
Feature/mcp server
2 parents a2ce144 + 65f1f1d commit 1f385ba

33 files changed

Lines changed: 1754 additions & 353 deletions

‎README.md‎

Lines changed: 118 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,22 @@
1+
12
# Ark
23

3-
> Yet another alternate \[directory | repository\] represent text generator tool
4+
> Yet another alternate \[directory | repository\] text generator tool
45
5-
**ark** is a powerful CLI tool designed to recursively scan a directory and generate a readable and well-formatted text representation of its structure and contents. Ideal for:
6+
**ark** recursively scans a directory and produces a clean, human‑readable dump of the tree and file contents. Perfect for
67

7-
* 📚 Sharing codebases with LLMs
8-
* 🧪 Static analysis workflows
9-
* 🗂️ Snapshotting source trees with clean formatting
8+
* 📚 sharing codebases with LLMs
9+
* 🧪 static‑analysis pipelines
10+
* 🗂️ snapshotting source trees
1011

11-
Supports both **plaintext**, **markdown**, **xml**, and **arklite** outputs, full UTF-8 support with optional skip behavior, and extensive filtering options.
12+
It supports **plaintext**, **markdown**, **XML**, and **arklite** outputs, full UTF‑8 handling (with optional skip), and extensive filtering.
1213

1314
---
1415

1516
## 🚀 Quick Start
1617

18+
### 1 · Install
19+
1720
### 1. Installation
1821

1922
```bash
@@ -30,63 +33,97 @@ Or download a pre-built binary from [Releases](https://github.com/magicdrive/ark
3033

3134
---
3235

33-
### 2. Generate ark-output.txt
36+
### 2 · Generate an output file
3437

3538
```bash
36-
ark <dirname>
39+
ark <dirname> # creates ark_output.txt in the cwd
3740
```
3841

3942
---
4043

41-
## 🧰 Usage
44+
## 🧰 Basic Usage
4245

43-
```sh
46+
```text
4447
ark [OPTIONS] <dirname>
48+
ark mcp-server [OPTIONS]
4549
```
4650

47-
### Arguments
51+
---
52+
53+
## 📂 Sub‑commands
4854

49-
| Argument | Description |
50-
| --------------- | --------------------------------------- |
51-
| `<dirname>` | The target directory to scan |
52-
| `<byte-string>` | Byte size string (e.g. 10M, 100k) |
53-
| `<extension>` | File extension name (e.g. go, ts, html) |
54-
| `<regexp>` | Regular expression string (Go syntax) |
55+
| Command | Description |
56+
|--------------|--------------------------------|
57+
| `mcp-server` | Run Ark as an HTTP MCP server. |
5558

5659
---
5760

58-
## ⚙️ Options
59-
60-
| Option | Alias | Description |
61-
| ------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------|
62-
| `--help` | `-h` | Show help message and exit |
63-
| `--version` | `-v` | Show version |
64-
| `--output-filename <filename>` | `-o` | Output file name (default: `ark-output.txt`) |
65-
| `--scan-buffer <byte-string>` | `-b` | Line scan buffer size (default: `10M`) |
66-
| `--output-format <'txt'\|'md'\|'xml'\|'arklite'>` | `-f` | Output file format (default: `txt`) |
67-
| `--mask-secrets <'on'\|'off'>` | `-m` | Detect secrets and mask them (default: `on`) |
68-
| `--allow-gitignore <'on'\|'off'>` | `-a` | Enable `.gitignore` filter |
69-
| `--additionally-ignorerule <filepath>` | `-p` | Additional `.gitignore`-like rules |
70-
| `--with-line-number <'on'\|'off'>` | `-n` | Show line numbers (default: `on`) |
71-
| `--ignore-dotfile <'on'\|'off'>` | `-d` | Ignore dotfiles (default: `on`) |
72-
| `--pattern-regex <regexp>` | `-x` | File match pattern |
73-
| `--include-ext <ext>` | `-i` | Include file extensions (comma separated) |
74-
| `--exclude-dir-regex <regexp>` | `-g` | Exclude directories matching regex |
75-
| `--exclude-file-regex <regexp>` | `-G` | Exclude files matching regex |
76-
| `--exclude-ext <ext>` | `-e` | Exclude file extensions (comma separated) |
77-
| `--exclude-dir <dir>` | `-E` | Exclude specific directory names |
78-
| `--compless` | `-c` | Compless output with arklite (for txt,md,xml) |
79-
| `--skip-non-utf8` | `-s` | Skip non-UTF-8 files |
80-
| `--silent` | `-S` | Suppress logs |
81-
| `--delete-comments` | `-D` | Strip comments based on language detection |
61+
## ⚙️ General Options
62+
63+
| Option | Alias | Description | Default |
64+
|--------|-------|-------------|---------|
65+
| `--help` | `-h` | Show help and exit | – |
66+
| `--version` | `-v` | Show version | – |
67+
| `--output-filename <file>` | `-o` | Name of the output file | `ark_output.txt` |
68+
| `--scan-buffer <size>` | `-b` | Read buffer size (`10M`, `500K`, …) | `10M` |
69+
| `--output-format <fmt>` | `-f` | `txt`, `md`, `xml`, `arklite` | `txt` |
70+
| `--mask-secrets <on/off>` | `-m` | Detect & mask secrets | `on` |
71+
| `--allow-gitignore <on/off>` | `-a` | Obey `.gitignore` rules | `on` |
72+
| `--additionally-ignorerule <file>` | `-A` | Extra ignore‑rule file | – |
73+
| `--with-line-number <on/off>` | `-n` | Prepend line numbers | `on` |
74+
| `--ignore-dotfile <on/off>` | `-d` | Skip dotfiles | `off` |
75+
| `--pattern-regex <regexp>` | `-x` | Include paths matching regexp | – |
76+
| `--include-ext <exts>` | `-i` | Include only ext(s) (`go,ts,html`) | – |
77+
| `--exclude-dir-regex <regexp>` | `-g` | Exclude dirs matching regexp | – |
78+
| `--exclude-file-regex <regexp>` | `-G` | Exclude files matching regexp | – |
79+
| `--exclude-ext <exts>` | `-e` | Exclude ext(s) | – |
80+
| `--exclude-dir <names>` | `-E` | Exclude dirs by name | – |
81+
| `--compless` | `-c` | Compress result with **arklite** | – |
82+
| `--skip-non-utf8` | `-s` | Ignore non‑UTF‑8 files | – |
83+
| `--silent` | `-S` | Suppress logs / progress | – |
84+
| `--delete-comments` | `-D` | Strip comments (language‑aware) | – |
8285

8386
---
8487

85-
## 📦 Output Format Examples
88+
## 🛰 mcp‑server Options
89+
90+
| Option | Alias | Description | Default |
91+
|--------|-------|-------------|---------|
92+
| `--root <dir>` | `-r` | Serve directory root | `$PWD` |
93+
| `--port <port>` | `-p` | HTTP listen port | `8522` |
94+
| `--scan-buffer <size>` | `-b` | Read buffer size (`10M`, `500K`, …) | `10M` |
95+
| `--mask-secrets <on/off>` | `-m` | Detect & mask secrets | `on` |
96+
| `--allow-gitignore <on/off>` | `-a` | Obey `.gitignore` rules | `on` |
97+
| `--additionally-ignorerule <file>` | `-A` | Extra ignore‑rule file | – |
98+
| `--ignore-dotfile <on/off>` | `-d` | Skip dotfiles | `off` |
99+
| `--pattern-regex <regexp>` | `-x` | Include paths matching regexp | – |
100+
| `--include-ext <exts>` | `-i` | Include only ext(s) (`go,ts,html`) | – |
101+
| `--exclude-dir-regex <regexp>` | `-g` | Exclude dirs matching regexp | – |
102+
| `--exclude-file-regex <regexp>` | `-G` | Exclude files matching regexp | – |
103+
| `--exclude-ext <exts>` | `-e` | Exclude ext(s) | – |
104+
| `--exclude-dir <names>` | `-E` | Exclude dirs by name | – |
105+
| `--skip-non-utf8` | `-s` | Ignore non‑UTF‑8 files | – |
106+
| `--delete-comments` | `-D` | Strip comments (language‑aware) | – |
86107

87-
### Plaintext (`--output-format txt`)
108+
---
88109

89-
```
110+
## 📝 Arguments
111+
112+
| Argument | Description |
113+
|----------|-------------|
114+
| `<dirname>` | Directory to scan |
115+
| `<byte-string>` | Size string (`10M`, `100K`, …) |
116+
| `<extension>` | File extension (`go`, `ts`, `html`) |
117+
| `<regexp>` | Go `regexp` syntax pattern |
118+
119+
---
120+
121+
## 📦 Output Examples
122+
123+
<details>
124+
<summary>Plaintext <code>(--output-format txt)</code></summary>
125+
126+
```text
90127
example_project
91128
├── main.go
92129
└── sub
@@ -95,14 +132,13 @@ example_project
95132
=== sub/sub.txt ===
96133
hello world
97134
```
135+
</details>
98136

99-
---
100-
101-
### Markdown (`--output-format md`)
137+
<details>
138+
<summary>Markdown <code>(--output-format md)</code></summary>
102139

103140
````markdown
104141
# Project Tree
105-
106142
```
107143
example_project
108144
├── main.go
@@ -117,131 +153,102 @@ example_project
117153
hello world
118154
```
119155
````
156+
</details>
120157

121-
---
122-
123-
### XML (`--output-format xml`)
158+
<details>
159+
<summary>XML <code>(--output-format xml)</code></summary>
124160

125161
```xml
126162
<?xml version="1.0" encoding="UTF-8"?>
127163
<ProjectDump>
128164
<Description>
129165
<ProjectName>example_project</ProjectName>
130-
<ProjectPath>/absolute/path/to/example_project</ProjectPath>
166+
<ProjectPath>/abs/path/example_project</ProjectPath>
131167
</Description>
132-
<Tree>
133-
<![CDATA[
168+
<Tree><![CDATA[
134169
example_project
135170
├── main.go
136171
└── sub
137172
└── sub.txt
138-
]]>
139-
</Tree>
173+
]]></Tree>
140174
<Files>
141-
<File path="main.go">
142-
<![CDATA[
175+
<File path="main.go"><![CDATA[
143176
package main
144-
func main() {
145-
println("hello")
146-
}
147-
]]>
148-
</File>
149-
<File path="sub/sub.txt">
150-
<![CDATA[
177+
func main() { println("hello") }
178+
]]></File>
179+
<File path="sub/sub.txt"><![CDATA[
151180
hello world
152-
]]>
153-
</File>
181+
]]></File>
154182
</Files>
155183
</ProjectDump>
156184
```
185+
</details>
157186

158-
---
159-
160-
### Arklite (`--output-format arklite`)
187+
<details>
188+
<summary>Arklite <code>(--output-format arklite)</code></summary>
161189

162190
```
163-
# Arklite Format: example_project (/absolute/path/to/example_project)
191+
# Arklite Format: example_project (/abs/path/example_project)
164192
165193
## Directory Tree (JSON)
166194
{"name":"example_project","type":"directory","children":[{"name":"main.go","type":"file"},{"name":"sub","type":"directory","children":[{"name":"sub.txt","type":"file"}]}]}
167195
168196
## File Dump
169197
@main.go
170-
package main␤func main() {␤ println("hello")␤}
198+
package main␤func main(){␤println("hello")␤}
171199
@sub/sub.txt
172200
hello world
173201
```
202+
</details>
174203

175204
---
176205

206+
## 🤔 What is Arklite?
177207

178-
#### 🤔 What's Arklite?
179-
180-
Arklite format is a highly compact format tailored for LLM input efficiency. It consists of:
181-
182-
1. 📝 A natural language description (project name and absolute path)
183-
2. 🗂 A JSON-based directory structure
184-
3. 📄 A one-line-per-file representation of all text content (with comments stripped)
185-
186-
Each file is prefixed with `@<relative path>` followed by a newline-delimited (`␤`) single-line content.
187-
188-
#### Example
189-
190-
```
191-
## Project: example_project
192-
## Path: /absolute/path/to/example_project
193-
194-
## Directory Tree (JSON)
195-
{"name":"example_project","type":"directory","children":[{"name":"main.go","type":"file"},{"name":"sub","type":"directory","children":[{"name":"sub.txt","type":"file"}]}]}
196-
197-
## File Dump
198-
@main.go
199-
package␤main␤func␤main(){␤fmt.Println("hello")}
200-
@sub/sub.txt
201-
hello␤world
202-
```
208+
Arklite is a compact single‑line‑per‑file format tuned for LLM token efficiency:
203209

204-
This format is designed to be minimal and structured for high compression in LLM token space.
210+
1. Natural‑language header (project + path)
211+
2. JSON directory tree
212+
3. File dump (`@path` + content with `␤` for newlines)
205213

214+
---
206215

207216
## 🗂 Example `.arkignore`
208217

209-
```
210-
# =============================
211-
# VCS / Version Control
212-
# =============================
218+
```gitignore
219+
# VCS
213220
.git/
214221
.hg/
215222
.svn/
216223
217-
# =============================
218-
# Editors / IDEs
219-
# =============================
224+
# IDEs / editors
220225
.idea/
221226
.vscode/
222227
*.code-workspace
223-
*.sublime-project
224-
*.sublime-workspace
228+
*.sublime-*
225229
```
226230

227231
---
228232

229-
## 🧩 Integrations
233+
## 🧩 Shell Completions
230234

231235
```sh
236+
# Bash & Zsh
232237
source completions/ark-completion.sh
238+
# Fish
239+
funcsave ark
233240
```
234241

235242
---
236243

237244
## 📎 See Also
238245

239-
- Project: https://github.com/magicdrive/ark
246+
* Project home — <https://github.com/magicdrive/ark>
240247

241248
## Author
242249

243-
(c) 2025 Hiroshi IKEGAMI
250+
© 2025 Hiroshi IKEGAMI
244251

245252
## License
246253

247-
This project is licensed under the [MIT License](https://github.com/magicdrive/ark/blob/main/LICENSE)
254+
Released under the [MIT License](LICENSE)

0 commit comments

Comments
 (0)