@shaifulshabuj-waymarks/server 0.2.0 → 0.3.1
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 +73 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# @shaifulshabuj-waymarks/server
|
|
2
|
+
|
|
3
|
+
MCP server and REST API backend for [Waymark](https://github.com/waymarks/waymark).
|
|
4
|
+
|
|
5
|
+
> **This package is installed automatically** by `@shaifulshabuj-waymarks/cli`.
|
|
6
|
+
> End users should not install it directly.
|
|
7
|
+
|
|
8
|
+
```bash
|
|
9
|
+
# Correct — install the CLI, which pulls in this package
|
|
10
|
+
npx @shaifulshabuj-waymarks/cli init
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## What this package provides
|
|
16
|
+
|
|
17
|
+
Two long-running Node.js processes, both spawned by `waymark start`:
|
|
18
|
+
|
|
19
|
+
| Process | Entry point | What it does |
|
|
20
|
+
|---------|-------------|--------------|
|
|
21
|
+
| MCP server | `dist/mcp/server.js` | stdio MCP server — intercepts Claude Code tool calls, enforces policy, logs actions |
|
|
22
|
+
| API server | `dist/api/server.js` | HTTP server on port 3001 — serves dashboard UI and REST API |
|
|
23
|
+
|
|
24
|
+
Both processes share the same SQLite database (`<project-root>/data/waymark.db`). The MCP process writes; the API process reads. All database calls are synchronous (`better-sqlite3`) so concurrent access is safe.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Environment variables
|
|
29
|
+
|
|
30
|
+
| Variable | Required | Default | Description |
|
|
31
|
+
|----------|----------|---------|-------------|
|
|
32
|
+
| `WAYMARK_PROJECT_ROOT` | Yes | `process.cwd()` | Absolute path to the project being monitored. Sets where `waymark.config.json` and `data/waymark.db` are resolved. |
|
|
33
|
+
| `PORT` | No | `3001` | Port for the API + dashboard server. |
|
|
34
|
+
| `WAYMARK_SLACK_WEBHOOK_URL` | No | — | Incoming webhook URL for Slack notifications on pending actions. |
|
|
35
|
+
| `WAYMARK_SLACK_CHANNEL` | No | — | Slack channel to post to (e.g. `#engineering`). |
|
|
36
|
+
| `WAYMARK_BASE_URL` | No | `http://localhost:3001` | Base URL used in Slack message links back to the dashboard. |
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## REST API
|
|
41
|
+
|
|
42
|
+
All endpoints are served by `dist/api/server.js` on port 3001.
|
|
43
|
+
|
|
44
|
+
| Method | Path | Description |
|
|
45
|
+
|--------|------|-------------|
|
|
46
|
+
| `GET` | `/api/actions` | List all logged actions. Query: `?count=true` returns `{ count: N }` for pending actions only. |
|
|
47
|
+
| `GET` | `/api/actions/:id` | Get a single action by ID. |
|
|
48
|
+
| `GET` | `/api/actions/:id/status` | Get the current status of an action (`pending`, `approved`, `rejected`, `blocked`, `allowed`). |
|
|
49
|
+
| `POST` | `/api/actions/:id/approve` | Approve a pending action — executes the held write and marks it approved. |
|
|
50
|
+
| `POST` | `/api/actions/:id/reject` | Reject a pending action — marks it rejected, action is not executed. |
|
|
51
|
+
| `POST` | `/api/actions/:id/rollback` | Roll back an approved write_file action to its before-snapshot. |
|
|
52
|
+
| `POST` | `/api/slack/interact` | Slack interactive component handler (approve/reject from Slack message buttons). |
|
|
53
|
+
| `GET` | `/api/sessions` | List all session IDs that have logged actions. |
|
|
54
|
+
| `GET` | `/api/config` | Return the current parsed `waymark.config.json` for the active project. |
|
|
55
|
+
| `GET` | `*` | Catch-all — serves the dashboard `index.html`. |
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## MCP tools
|
|
60
|
+
|
|
61
|
+
The MCP server exposes three tools to Claude Code:
|
|
62
|
+
|
|
63
|
+
| Tool | Replaces | Description |
|
|
64
|
+
|------|----------|-------------|
|
|
65
|
+
| `waymark:write_file` | `write_file` | Write a file — subject to policy before execution. |
|
|
66
|
+
| `waymark:read_file` | `read_file` | Read a file — always logged. |
|
|
67
|
+
| `waymark:bash` | `bash` | Run a shell command — checked against `blockedCommands` before execution. |
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## License
|
|
72
|
+
|
|
73
|
+
MIT — see [LICENSE](https://github.com/waymarks/waymark/blob/main/LICENSE)
|