@typescape-ai/mcp 1.9.13 → 1.9.17
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 +135 -190
- package/dist/mcp.js +43 -4
- package/package.json +12 -5
package/README.md
CHANGED
|
@@ -1,22 +1,38 @@
|
|
|
1
1
|
# @typescape-ai/mcp
|
|
2
2
|
|
|
3
|
-
Typescape MCP
|
|
3
|
+
Typescape MCP server for external agent harnesses that need canonical review, finding, decision, rules, corpus, and export workflows.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The published package currently exposes 50 tools. MCP is the easiest discovery surface for agent clients such as Claude Code, Cursor, and Windsurf, but it is not the whole product surface. Typescape also ships the same operating model over the API and CLI.
|
|
6
6
|
|
|
7
7
|
## Requirements
|
|
8
8
|
|
|
9
|
-
- [Bun](https://bun.sh/)
|
|
9
|
+
- [Bun](https://bun.sh/) `>=1.0` is preferred
|
|
10
|
+
- [Node.js](https://nodejs.org/) `>=18.17` also works for `npx`-style launchers
|
|
11
|
+
- `TYPESCAPE_API_KEY` and `TYPESCAPE_BASE_URL`
|
|
10
12
|
|
|
11
|
-
##
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
Preferred ephemeral launch:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
bunx @typescape-ai/mcp
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
If you want to pin the package in a repo:
|
|
12
22
|
|
|
13
23
|
```bash
|
|
14
24
|
bun add -D @typescape-ai/mcp
|
|
15
25
|
```
|
|
16
26
|
|
|
17
|
-
|
|
27
|
+
Node-based MCP clients can also launch it without installing Bun:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npx -y @typescape-ai/mcp
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Client Config
|
|
18
34
|
|
|
19
|
-
|
|
35
|
+
Generic MCP config shape:
|
|
20
36
|
|
|
21
37
|
```json
|
|
22
38
|
{
|
|
@@ -25,17 +41,15 @@ Add to your Claude Code MCP settings (`~/.claude/mcp.json`):
|
|
|
25
41
|
"command": "bunx",
|
|
26
42
|
"args": ["@typescape-ai/mcp"],
|
|
27
43
|
"env": {
|
|
28
|
-
"TYPESCAPE_API_KEY": "
|
|
29
|
-
"TYPESCAPE_BASE_URL": "https://your-typescape-instance.
|
|
44
|
+
"TYPESCAPE_API_KEY": "ts_op_your_token",
|
|
45
|
+
"TYPESCAPE_BASE_URL": "https://your-typescape-instance.example.com"
|
|
30
46
|
}
|
|
31
47
|
}
|
|
32
48
|
}
|
|
33
49
|
}
|
|
34
50
|
```
|
|
35
51
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
Add to `.cursor/mcp.json` in your project:
|
|
52
|
+
Claude Code example: `~/.claude/mcp.json`
|
|
39
53
|
|
|
40
54
|
```json
|
|
41
55
|
{
|
|
@@ -44,239 +58,170 @@ Add to `.cursor/mcp.json` in your project:
|
|
|
44
58
|
"command": "bunx",
|
|
45
59
|
"args": ["@typescape-ai/mcp"],
|
|
46
60
|
"env": {
|
|
47
|
-
"TYPESCAPE_API_KEY": "
|
|
48
|
-
"TYPESCAPE_BASE_URL": "https://your-typescape-instance.
|
|
61
|
+
"TYPESCAPE_API_KEY": "ts_op_your_token",
|
|
62
|
+
"TYPESCAPE_BASE_URL": "https://your-typescape-instance.example.com"
|
|
49
63
|
}
|
|
50
64
|
}
|
|
51
65
|
}
|
|
52
66
|
}
|
|
53
67
|
```
|
|
54
68
|
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
## Quick Start Workflow
|
|
58
|
-
|
|
59
|
-
The typical 4-step happy path for an agent:
|
|
60
|
-
|
|
61
|
-
**1. Create a review session**
|
|
69
|
+
Cursor example: `.cursor/mcp.json`
|
|
62
70
|
|
|
63
71
|
```json
|
|
64
|
-
// typescape_create_session
|
|
65
72
|
{
|
|
66
|
-
"
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
**2. Get rendered blocks for anchoring**
|
|
77
|
-
|
|
78
|
-
```json
|
|
79
|
-
// typescape_get_render
|
|
80
|
-
{ "session_id": "sess_01HX..." }
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
// → { "blocks": [{ "block_id": "blk_...", "type": "paragraph", "html": "..." }, ...] }
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
**3. Create a thread on a specific block**
|
|
87
|
-
|
|
88
|
-
```json
|
|
89
|
-
// typescape_create_thread
|
|
90
|
-
{
|
|
91
|
-
"session_id": "sess_01HX...",
|
|
92
|
-
"block_id": "blk_...",
|
|
93
|
-
"body": "This section could be clearer about error handling.",
|
|
94
|
-
"severity": "suggestion"
|
|
73
|
+
"mcpServers": {
|
|
74
|
+
"typescape": {
|
|
75
|
+
"command": "npx",
|
|
76
|
+
"args": ["-y", "@typescape-ai/mcp"],
|
|
77
|
+
"env": {
|
|
78
|
+
"TYPESCAPE_API_KEY": "ts_op_your_token",
|
|
79
|
+
"TYPESCAPE_BASE_URL": "https://your-typescape-instance.example.com"
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
95
83
|
}
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
// → { "thread_id": "thr_...", "comment_id": "cmt_..." }
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
**4. Export structured feedback**
|
|
102
|
-
|
|
103
|
-
```json
|
|
104
|
-
// typescape_export_feedback
|
|
105
|
-
{ "session_id": "sess_01HX..." }
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
// → { "schema_version": "v1", "session": {...}, "threads": [...], "comments": [...] }
|
|
109
84
|
```
|
|
110
85
|
|
|
111
|
-
##
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
| `typescape_get_session` | Get full session metadata including participants, stats, and provenance. |
|
|
121
|
-
| `typescape_get_render` | Get rendered content with immutable block-level HTML structure and `block_id`s for anchoring. |
|
|
122
|
-
| `typescape_export_feedback` | Export all feedback as structured JSON (schema v1) including threads, comments, and anchors. |
|
|
123
|
-
| `typescape_export_response_matrix` | Export per-thread disposition and evidence summary. |
|
|
124
|
-
|
|
125
|
-
### Threads & Comments
|
|
126
|
-
|
|
127
|
-
| Tool | Description |
|
|
128
|
-
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
|
129
|
-
| `typescape_get_threads` | List threads for a session. Optionally filter by `block_id` or status. Returns paginated list with comments. |
|
|
130
|
-
| `typescape_create_thread` | Create a new thread on a block. Agent-created threads are tagged `source='automation'`. |
|
|
131
|
-
| `typescape_post_comment` | Post a reply to an existing thread. |
|
|
132
|
-
| `typescape_resolve_thread` | Resolve (close) a thread. Optionally include a disposition. Supports optimistic concurrency via `expected_version`. |
|
|
133
|
-
| `typescape_reopen_thread` | Reopen a previously resolved thread. Supports optimistic concurrency. |
|
|
134
|
-
| `typescape_record_disposition` | Record a disposition (decision) on a thread. A resolving disposition may auto-resolve the thread. |
|
|
135
|
-
| `typescape_attach_evidence` | Attach evidence to a thread (commit SHA, proposed change, PR URL, attestation, external ticket, or note). |
|
|
136
|
-
|
|
137
|
-
### Review References
|
|
138
|
-
|
|
139
|
-
| Tool | Description |
|
|
140
|
-
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
141
|
-
| `typescape_create_review_ref` | Create a stable review reference that tracks the HEAD session for doc/file/PR/custom keys. Always available (core primitive). |
|
|
142
|
-
| `typescape_resolve_review_ref` | Resolve a review ref to its current head session ID and pinned content details. |
|
|
143
|
-
| `typescape_advance_review_ref` | Advance a review ref to a new head session. Supports optimistic concurrency via `expected_head_session_id`. |
|
|
86
|
+
## Canonical Workflows
|
|
87
|
+
|
|
88
|
+
Review workflow:
|
|
89
|
+
|
|
90
|
+
1. `typescape_create_review`
|
|
91
|
+
2. `typescape_get_render`
|
|
92
|
+
3. `typescape_create_finding`
|
|
93
|
+
4. `typescape_post_comment` / `typescape_record_decision`
|
|
94
|
+
5. `typescape_export_review`
|
|
144
95
|
|
|
145
|
-
|
|
96
|
+
Rules workflow:
|
|
146
97
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
98
|
+
1. `typescape_get_rules`
|
|
99
|
+
2. `typescape_check_content`
|
|
100
|
+
3. `typescape_import_rules` or `typescape_propose_rule`
|
|
101
|
+
4. `typescape_list_rule_proposals`
|
|
102
|
+
5. `typescape_decide_rule_proposal`
|
|
151
103
|
|
|
152
|
-
|
|
104
|
+
API/CLI parity:
|
|
153
105
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
106
|
+
- API is the canonical automation contract. See [../../docs/api.md](../../docs/api.md).
|
|
107
|
+
- CLI is the first-class terminal surface for the same review and rules workflows. See [../cli/README.md](../cli/README.md).
|
|
108
|
+
- MCP is the adapter/discovery surface for agent clients that already speak MCP.
|
|
157
109
|
|
|
158
|
-
|
|
110
|
+
## Tool Families
|
|
159
111
|
|
|
160
|
-
|
|
112
|
+
Reviews:
|
|
161
113
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
114
|
+
- `typescape_create_review`
|
|
115
|
+
- `typescape_revise_review`
|
|
116
|
+
- `typescape_export_review`
|
|
117
|
+
- `typescape_list_reviews`
|
|
118
|
+
- `typescape_get_review`
|
|
119
|
+
- `typescape_get_render`
|
|
120
|
+
- `typescape_search_reviews`
|
|
121
|
+
- `typescape_close_review`
|
|
122
|
+
- `typescape_reopen_review`
|
|
123
|
+
- `typescape_export_response_matrix`
|
|
166
124
|
|
|
167
|
-
|
|
125
|
+
Findings, comments, decisions, and evidence:
|
|
168
126
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
127
|
+
- `typescape_list_findings`
|
|
128
|
+
- `typescape_search_findings`
|
|
129
|
+
- `typescape_create_finding`
|
|
130
|
+
- `typescape_post_comment`
|
|
131
|
+
- `typescape_resolve_finding`
|
|
132
|
+
- `typescape_reopen_finding`
|
|
133
|
+
- `typescape_record_decision`
|
|
134
|
+
- `typescape_attach_evidence`
|
|
135
|
+
- `typescape_get_decision`
|
|
136
|
+
- `typescape_list_evidence`
|
|
175
137
|
|
|
176
|
-
|
|
138
|
+
Review sets and refs:
|
|
177
139
|
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
| `typescape_steering_dashboard` | Get aggregate steering health: active rule count, average health, degraded rules. | `features.steering` |
|
|
184
|
-
| `typescape_promote_gci` | Convert an approved GCI into a steering proposal for operator acceptance. | `features.steering` |
|
|
185
|
-
| `typescape_decide_proposal` | Accept, reject, or deprecate a steering proposal. Accepting activates the rule immediately. | `features.steering` |
|
|
140
|
+
- `typescape_create_review_set`
|
|
141
|
+
- `typescape_export_review_set`
|
|
142
|
+
- `typescape_create_review_ref`
|
|
143
|
+
- `typescape_resolve_review_ref`
|
|
144
|
+
- `typescape_advance_review_ref`
|
|
186
145
|
|
|
187
|
-
|
|
146
|
+
Approvals, checks, account, and capabilities:
|
|
188
147
|
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
- `
|
|
148
|
+
- `typescape_request_approval`
|
|
149
|
+
- `typescape_get_status`
|
|
150
|
+
- `typescape_run_checks`
|
|
151
|
+
- `typescape_account_usage`
|
|
152
|
+
- `typescape_account_plan`
|
|
153
|
+
- `typescape_get_capabilities`
|
|
192
154
|
|
|
193
|
-
|
|
155
|
+
Corpus:
|
|
194
156
|
|
|
195
|
-
|
|
157
|
+
- `typescape_get_snapshot`
|
|
158
|
+
- `typescape_list_backlinks`
|
|
159
|
+
- `typescape_get_impact`
|
|
196
160
|
|
|
197
|
-
|
|
161
|
+
Rules:
|
|
198
162
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
163
|
+
- `typescape_get_rules`
|
|
164
|
+
- `typescape_rules_pack`
|
|
165
|
+
- `typescape_check_content`
|
|
166
|
+
- `typescape_import_rules`
|
|
167
|
+
- `typescape_propose_rule`
|
|
168
|
+
- `typescape_list_rule_proposals`
|
|
169
|
+
- `typescape_list_rule_proposals_legacy`
|
|
170
|
+
- `typescape_rules_dashboard`
|
|
171
|
+
- `typescape_promote_rule_proposal`
|
|
172
|
+
- `typescape_decide_rule_proposal`
|
|
202
173
|
|
|
203
|
-
|
|
174
|
+
Repo, asset, and collection support:
|
|
204
175
|
|
|
205
|
-
- `
|
|
206
|
-
- `
|
|
207
|
-
- `
|
|
208
|
-
- `
|
|
209
|
-
- `
|
|
176
|
+
- `typescape_list_repos`
|
|
177
|
+
- `typescape_connect_repo`
|
|
178
|
+
- `typescape_repo_branches`
|
|
179
|
+
- `typescape_upload_reviewer_asset`
|
|
180
|
+
- `typescape_create_collection`
|
|
181
|
+
- `typescape_add_review_to_collection`
|
|
210
182
|
|
|
211
|
-
|
|
183
|
+
## Notes
|
|
212
184
|
|
|
213
|
-
-
|
|
214
|
-
-
|
|
215
|
-
-
|
|
216
|
-
- If server returns `feature_disabled` for `inline_assets_enabled`, MCP auto-falls back to upload-batch creation via `/projects/:id/upload`
|
|
185
|
+
- `typescape_list_rule_proposals_legacy` exists only as a bounded compatibility surface while the rules cutover finishes. New integrations should prefer `typescape_list_rule_proposals`.
|
|
186
|
+
- Approval submission is still a human action. MCP can request approval and read status, but it does not replace the reviewer/operator approval flow.
|
|
187
|
+
- Feature-gated tools return `feature_disabled` when the backing capability is off for the tenant.
|
|
217
188
|
|
|
218
|
-
|
|
189
|
+
## Response Shape
|
|
190
|
+
|
|
191
|
+
Every MCP tool returns JSON text in `content[0].text`.
|
|
219
192
|
|
|
220
|
-
|
|
221
|
-
- `pdf` (use `filename`/`file_path` with either inline or upload-backed source)
|
|
222
|
-
- `image_set` (use `filenames` with either inline or upload-backed source)
|
|
223
|
-
|
|
224
|
-
All tool responses return JSON in `content[0].text`:
|
|
193
|
+
Success example:
|
|
225
194
|
|
|
226
195
|
```json
|
|
227
196
|
{
|
|
228
197
|
"content": [
|
|
229
|
-
{
|
|
198
|
+
{
|
|
199
|
+
"type": "text",
|
|
200
|
+
"text": "{\"review_id\":\"sess_01HX...\",\"request_id\":\"req_abc123\"}"
|
|
201
|
+
}
|
|
230
202
|
]
|
|
231
203
|
}
|
|
232
204
|
```
|
|
233
205
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
**Error shape:**
|
|
206
|
+
Error example:
|
|
237
207
|
|
|
238
208
|
```json
|
|
239
209
|
{
|
|
240
210
|
"error": {
|
|
241
|
-
"code": "
|
|
242
|
-
"message": "No
|
|
211
|
+
"code": "review_not_found",
|
|
212
|
+
"message": "No review with that ID exists.",
|
|
243
213
|
"retryable": false,
|
|
244
214
|
"request_id": "req_abc123"
|
|
245
215
|
}
|
|
246
216
|
}
|
|
247
217
|
```
|
|
248
218
|
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
## Feature Gates Summary
|
|
252
|
-
|
|
253
|
-
| Feature Flag | Tools Gated |
|
|
254
|
-
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
255
|
-
| `features.review_sets` | `create_review_set`, `export_review_set` |
|
|
256
|
-
| `features.policy` | `get_status` |
|
|
257
|
-
| `features.checks` | `run_checks` |
|
|
258
|
-
| `features.corpus_snapshots` | `get_snapshot`, `list_backlinks`, `get_impact` |
|
|
259
|
-
| `features.steering` | `get_steering`, `create_gci`, `list_gcis`, `list_proposals`, `steering_dashboard`, `promote_gci`, `decide_proposal` |
|
|
260
|
-
|
|
261
|
-
Tools without a feature gate are always available when the MCP server is running.
|
|
262
|
-
|
|
263
|
-
When a gated tool is called without its feature enabled, it returns:
|
|
264
|
-
|
|
265
|
-
```json
|
|
266
|
-
{
|
|
267
|
-
"error": {
|
|
268
|
-
"code": "feature_disabled",
|
|
269
|
-
"message": "Feature 'steering' is not enabled"
|
|
270
|
-
}
|
|
271
|
-
}
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
## Environment Variables
|
|
219
|
+
## Environment
|
|
275
220
|
|
|
276
|
-
| Variable | Required | Description
|
|
277
|
-
| -------------------- | -------- |
|
|
278
|
-
| `TYPESCAPE_API_KEY` | Yes | Operator API token
|
|
279
|
-
| `TYPESCAPE_BASE_URL` | Yes | Typescape server URL |
|
|
221
|
+
| Variable | Required | Description |
|
|
222
|
+
| -------------------- | -------- | ------------------------- |
|
|
223
|
+
| `TYPESCAPE_API_KEY` | Yes | Operator API token |
|
|
224
|
+
| `TYPESCAPE_BASE_URL` | Yes | Typescape server base URL |
|
|
280
225
|
|
|
281
226
|
## License
|
|
282
227
|
|