@velvetmonkey/flywheel-crank 0.1.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/LICENSE +661 -0
- package/README.md +154 -0
- package/dist/index.js +1195 -0
- package/package.json +49 -0
package/README.md
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# Flywheel Crank MCP Server
|
|
2
|
+
|
|
3
|
+
Deterministic vault mutations for [Obsidian](https://obsidian.md/) via MCP. The write companion to [Flywheel](https://github.com/velvetmonkey/flywheel).
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@velvetmonkey/flywheel-crank)
|
|
6
|
+
[](https://www.gnu.org/licenses/agpl-3.0)
|
|
7
|
+
[](https://modelcontextprotocol.io/)
|
|
8
|
+
|
|
9
|
+
## What is Flywheel Crank?
|
|
10
|
+
|
|
11
|
+
While **Flywheel** provides read-only graph intelligence (backlinks, queries, structure analysis), **Crank** enables **surgical vault mutations**:
|
|
12
|
+
|
|
13
|
+
- Add/remove/replace content in sections
|
|
14
|
+
- Toggle and create tasks
|
|
15
|
+
- Update frontmatter
|
|
16
|
+
- Create and delete notes
|
|
17
|
+
- Auto-commit with undo support
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
### Via `.mcp.json`
|
|
22
|
+
|
|
23
|
+
Add to your project's `.mcp.json` (in your vault root). **Zero-config** if `.mcp.json` is in your vault:
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"mcpServers": {
|
|
28
|
+
"flywheel-crank": {
|
|
29
|
+
"command": "npx",
|
|
30
|
+
"args": ["-y", "@velvetmonkey/flywheel-crank"],
|
|
31
|
+
"env": {
|
|
32
|
+
"AUTO_COMMIT": "true"
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
> **Note**: Windows native requires `"command": "cmd", "args": ["/c", "npx", "-y", "@velvetmonkey/flywheel-crank"]`
|
|
40
|
+
|
|
41
|
+
<details>
|
|
42
|
+
<summary><strong>Advanced: Pointing to a different vault</strong></summary>
|
|
43
|
+
|
|
44
|
+
If `.mcp.json` is NOT in your vault, set `PROJECT_PATH`:
|
|
45
|
+
|
|
46
|
+
**Linux / macOS / WSL:**
|
|
47
|
+
|
|
48
|
+
```json
|
|
49
|
+
{
|
|
50
|
+
"mcpServers": {
|
|
51
|
+
"flywheel-crank": {
|
|
52
|
+
"command": "npx",
|
|
53
|
+
"args": ["-y", "@velvetmonkey/flywheel-crank"],
|
|
54
|
+
"env": {
|
|
55
|
+
"PROJECT_PATH": "/path/to/your/vault",
|
|
56
|
+
"AUTO_COMMIT": "true"
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Windows (native):**
|
|
64
|
+
|
|
65
|
+
```json
|
|
66
|
+
{
|
|
67
|
+
"mcpServers": {
|
|
68
|
+
"flywheel-crank": {
|
|
69
|
+
"command": "cmd",
|
|
70
|
+
"args": ["/c", "npx", "-y", "@velvetmonkey/flywheel-crank"],
|
|
71
|
+
"env": {
|
|
72
|
+
"PROJECT_PATH": "C:/Users/yourname/path/to/vault",
|
|
73
|
+
"AUTO_COMMIT": "true"
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
</details>
|
|
81
|
+
|
|
82
|
+
### Via CLI
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# Zero-config (run from vault directory)
|
|
86
|
+
claude mcp add flywheel-crank -e AUTO_COMMIT=true -- npx -y @velvetmonkey/flywheel-crank
|
|
87
|
+
|
|
88
|
+
# With explicit vault path
|
|
89
|
+
claude mcp add flywheel-crank -e PROJECT_PATH=/path/to/vault -e AUTO_COMMIT=true -- npx -y @velvetmonkey/flywheel-crank
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Verify
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
claude mcp list # Should show: flywheel-crank
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Tools
|
|
99
|
+
|
|
100
|
+
| Category | Tools |
|
|
101
|
+
|----------|-------|
|
|
102
|
+
| Mutations | `vault_add_to_section`, `vault_remove_from_section`, `vault_replace_in_section` |
|
|
103
|
+
| Tasks | `vault_toggle_task`, `vault_add_task` |
|
|
104
|
+
| Frontmatter | `vault_update_frontmatter`, `vault_add_frontmatter_field` |
|
|
105
|
+
| Notes | `vault_create_note`, `vault_delete_note` |
|
|
106
|
+
| System | `vault_list_sections`, `vault_undo_last_mutation` |
|
|
107
|
+
|
|
108
|
+
## Configuration
|
|
109
|
+
|
|
110
|
+
| Environment Variable | Required | Default | Description |
|
|
111
|
+
|---------------------|:--------:|---------|-------------|
|
|
112
|
+
| `PROJECT_PATH` | No | `cwd()` | Path to markdown vault directory |
|
|
113
|
+
| `AUTO_COMMIT` | No | `false` | Auto-commit mutations to git |
|
|
114
|
+
|
|
115
|
+
## Design Principles
|
|
116
|
+
|
|
117
|
+
- **Deterministic**: No AI-driven edits, predictable output
|
|
118
|
+
- **Atomic**: Each mutation is a single, reversible operation
|
|
119
|
+
- **Safe**: Path sandboxing, auto-commit, undo support
|
|
120
|
+
- **Obsidian-compatible**: Follows Obsidian conventions (task format, wikilinks, etc.)
|
|
121
|
+
|
|
122
|
+
## Flywheel + Crank
|
|
123
|
+
|
|
124
|
+
Use both together for full vault intelligence:
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"mcpServers": {
|
|
129
|
+
"flywheel": {
|
|
130
|
+
"command": "npx",
|
|
131
|
+
"args": ["-y", "@velvetmonkey/flywheel-mcp"]
|
|
132
|
+
},
|
|
133
|
+
"flywheel-crank": {
|
|
134
|
+
"command": "npx",
|
|
135
|
+
"args": ["-y", "@velvetmonkey/flywheel-crank"],
|
|
136
|
+
"env": { "AUTO_COMMIT": "true" }
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- **Flywheel**: Query, search, analyze (read-only)
|
|
143
|
+
- **Crank**: Mutate, create, update (write)
|
|
144
|
+
|
|
145
|
+
## License
|
|
146
|
+
|
|
147
|
+
AGPL-3.0 — [Ben Cassie](https://github.com/velvetmonkey)
|
|
148
|
+
|
|
149
|
+
## Links
|
|
150
|
+
|
|
151
|
+
- [Flywheel](https://github.com/velvetmonkey/flywheel) — Read-only graph intelligence
|
|
152
|
+
- [Flywheel Crank](https://github.com/velvetmonkey/flywheel-crank) — This project
|
|
153
|
+
- [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
154
|
+
- [Claude Code](https://claude.ai/code)
|