groundwork-mcp 0.1.0 → 0.3.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/NOTICE +1 -1
- package/README.md +15 -3
- package/SPEC.md +2 -0
- package/dist/{chunk-3W4X6WV2.js → chunk-3YZLRKZH.js} +133 -13
- package/dist/chunk-3YZLRKZH.js.map +1 -0
- package/dist/{chunk-NRKF6WRA.js → chunk-DU4P7DDY.js} +2 -2
- package/dist/cli.js +107 -4
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +13 -2
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp.js +2 -2
- package/package.json +4 -4
- package/dist/chunk-3W4X6WV2.js.map +0 -1
- /package/dist/{chunk-NRKF6WRA.js.map → chunk-DU4P7DDY.js.map} +0 -0
package/NOTICE
CHANGED
package/README.md
CHANGED
|
@@ -26,7 +26,7 @@ claude mcp add groundwork -- npx -y groundwork-mcp
|
|
|
26
26
|
Or install the plugin, which adds the MCP server and a skill that teaches Claude when to use it:
|
|
27
27
|
|
|
28
28
|
```
|
|
29
|
-
/plugin marketplace add
|
|
29
|
+
/plugin marketplace add IdeatorlabsAB/groundwork
|
|
30
30
|
/plugin install groundwork@groundwork
|
|
31
31
|
```
|
|
32
32
|
|
|
@@ -49,6 +49,7 @@ npx -p groundwork-mcp groundwork init # create groundwork/config.yml
|
|
|
49
49
|
npx -p groundwork-mcp groundwork validate # check every item and link; exits 1 on errors
|
|
50
50
|
npx -p groundwork-mcp groundwork trace REQ-0002
|
|
51
51
|
npx -p groundwork-mcp groundwork list hypothesis
|
|
52
|
+
npx -p groundwork-mcp groundwork import --to <web app> # see "Groundwork for teams"
|
|
52
53
|
```
|
|
53
54
|
|
|
54
55
|
`trace` shows the chain behind an item (from [examples/acme](examples/acme)):
|
|
@@ -81,7 +82,7 @@ jobs:
|
|
|
81
82
|
|
|
82
83
|
## Setup
|
|
83
84
|
|
|
84
|
-
`groundwork/config.yml` holds your product areas, products and people (for approvals). The first write creates it if it's missing. Fill it in so agents can tag items by area and send requirements for sign-off:
|
|
85
|
+
`groundwork/config.yml` holds your product areas, products and people (for approvals). The first write creates it if it's missing. Fill it in so agents can tag items by area and send requirements for sign-off. Agents can also add product areas and products themselves, with `add_product_areas` and `add_products`; people are always added by hand:
|
|
85
86
|
|
|
86
87
|
```yaml
|
|
87
88
|
name: Acme
|
|
@@ -107,6 +108,7 @@ The full format, every field and the rules are in [SPEC.md](SPEC.md). See [examp
|
|
|
107
108
|
| | `add_requirements` | `send_back_requirement` |
|
|
108
109
|
| | `update_item`, `link_items` | `obsolete_requirement` |
|
|
109
110
|
| | `delete_item` | |
|
|
111
|
+
| | `add_product_areas`, `add_products` | |
|
|
110
112
|
|
|
111
113
|
## Privacy
|
|
112
114
|
|
|
@@ -114,7 +116,17 @@ Insights hold what customers said, and these files usually end up in git. Ground
|
|
|
114
116
|
|
|
115
117
|
## Groundwork for teams
|
|
116
118
|
|
|
117
|
-
The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync for people who don't live in a terminal.
|
|
119
|
+
The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync for people who don't live in a terminal. It's a separate, paid product; this project is and stays open source.
|
|
120
|
+
|
|
121
|
+
To move a project into it, create an agent token in the web app (**Settings → Connect an agent**), then:
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
export GROUNDWORK_TOKEN=gw_…
|
|
125
|
+
npx -p groundwork-mcp groundwork import --to https://your-groundwork-app --dry-run # see what would happen
|
|
126
|
+
npx -p groundwork-mcp groundwork import --to https://your-groundwork-app
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Every item keeps its links, and its original id (`INS-0001`) is stored with it. Running the import again skips items already there (`--overwrite` replaces them). Afterwards `groundwork/config.yml` says `migrated:`, so local tools only read the files and the web app is where changes go. The command prints how to point your agent at the web app's MCP server.
|
|
118
130
|
|
|
119
131
|
## Contributing
|
|
120
132
|
|
package/SPEC.md
CHANGED
|
@@ -100,6 +100,8 @@ people:
|
|
|
100
100
|
migrated: https://… # set by the web app importer; local writes stop
|
|
101
101
|
```
|
|
102
102
|
|
|
103
|
+
`add_product_areas` and `add_products` append to `productAreas` and `products`. They skip entries already there (matched by label or name, ignoring case) and never rename, reorder or remove anything. Area ids are made from the label unless given. Rename or remove by editing the file.
|
|
104
|
+
|
|
103
105
|
The person acting is `$GROUNDWORK_USER` (a person id). Otherwise it's the person whose `email` matches git's, or the only person listed. If none of those apply, it's `me`.
|
|
104
106
|
|
|
105
107
|
## Versioning
|
|
@@ -633,6 +633,18 @@ function writeConfig(root, config) {
|
|
|
633
633
|
mkdirSync(join(root, DIR), { recursive: true });
|
|
634
634
|
writeFileSync(configPath(root), CONFIG_HEADER + YAML.stringify(config, { lineWidth: 0 }));
|
|
635
635
|
}
|
|
636
|
+
function appendToConfig(root, add) {
|
|
637
|
+
const file = configPath(root);
|
|
638
|
+
const doc = YAML.parseDocument(readFileSync(file, "utf8"));
|
|
639
|
+
for (const key of ["productAreas", "products"]) {
|
|
640
|
+
const values = add[key];
|
|
641
|
+
if (!values?.length) continue;
|
|
642
|
+
if (!YAML.isSeq(doc.get(key))) doc.set(key, doc.createNode([]));
|
|
643
|
+
const seq = doc.get(key);
|
|
644
|
+
for (const v of values) seq.add(doc.createNode(v));
|
|
645
|
+
}
|
|
646
|
+
writeFileSync(file, doc.toString({ lineWidth: 0 }));
|
|
647
|
+
}
|
|
636
648
|
function gitEmail(root) {
|
|
637
649
|
try {
|
|
638
650
|
return execFileSync("git", ["config", "user.email"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || void 0;
|
|
@@ -887,7 +899,58 @@ function validate(loaded, config) {
|
|
|
887
899
|
import { randomUUID } from "crypto";
|
|
888
900
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
889
901
|
import { z as z4 } from "zod";
|
|
890
|
-
|
|
902
|
+
|
|
903
|
+
// src/core/workspace.ts
|
|
904
|
+
var WorkspaceError = class extends Error {
|
|
905
|
+
};
|
|
906
|
+
var SLUG_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
|
|
907
|
+
function slugify(label) {
|
|
908
|
+
return label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
|
|
909
|
+
}
|
|
910
|
+
var same = (a, b) => a.trim().toLowerCase() === b.trim().toLowerCase();
|
|
911
|
+
function mergeAreas(existing, input) {
|
|
912
|
+
const list = [...existing];
|
|
913
|
+
const added = [];
|
|
914
|
+
const alreadyThere = [];
|
|
915
|
+
for (const raw of input) {
|
|
916
|
+
const label = raw.label.trim();
|
|
917
|
+
const given = raw.id?.trim();
|
|
918
|
+
const id = given ?? slugify(label);
|
|
919
|
+
if (!id) throw new WorkspaceError(`"${label}" has no letters or digits to make an id from. Give an id (lowercase letters, digits and dashes).`);
|
|
920
|
+
if (!SLUG_ID.test(id)) throw new WorkspaceError(`"${id}" isn't a valid area id: use up to 40 lowercase letters, digits and dashes, starting with a letter or digit.`);
|
|
921
|
+
const byLabel = list.find((a) => same(a.label, label));
|
|
922
|
+
if (byLabel) {
|
|
923
|
+
alreadyThere.push(byLabel);
|
|
924
|
+
continue;
|
|
925
|
+
}
|
|
926
|
+
const byId = list.find((a) => a.id === id);
|
|
927
|
+
if (byId) throw new WorkspaceError(`"${label}" would get the id "${id}", which "${byId.label}" already uses. Give a different id.`);
|
|
928
|
+
const area2 = { id, label };
|
|
929
|
+
list.push(area2);
|
|
930
|
+
added.push(area2);
|
|
931
|
+
}
|
|
932
|
+
return { list, added, alreadyThere };
|
|
933
|
+
}
|
|
934
|
+
function mergeProducts(existing, input) {
|
|
935
|
+
const list = [...existing];
|
|
936
|
+
const added = [];
|
|
937
|
+
const alreadyThere = [];
|
|
938
|
+
for (const raw of input) {
|
|
939
|
+
const name = raw.trim();
|
|
940
|
+
if (!name) throw new WorkspaceError("A product name can't be empty.");
|
|
941
|
+
const hit = list.find((p) => same(p, name));
|
|
942
|
+
if (hit) {
|
|
943
|
+
alreadyThere.push(hit);
|
|
944
|
+
continue;
|
|
945
|
+
}
|
|
946
|
+
list.push(name);
|
|
947
|
+
added.push(name);
|
|
948
|
+
}
|
|
949
|
+
return { list, added, alreadyThere };
|
|
950
|
+
}
|
|
951
|
+
|
|
952
|
+
// src/mcp/server.ts
|
|
953
|
+
var VERSION = true ? "0.3.0" : "0.0.0-dev";
|
|
891
954
|
var { insightInput: insightInput2, hypothesisInput: hypothesisInput2, experimentInput: experimentInput2, findingInput: findingInput2, requirementInput: requirementInput2, PATCHES } = localSchemas;
|
|
892
955
|
var INSTRUCTIONS = `Groundwork keeps this product's evidence and decisions as linked Markdown files in the groundwork/ folder, as a chain:
|
|
893
956
|
insight -> hypothesis -> experiment -> finding -> requirement.
|
|
@@ -899,7 +962,7 @@ insight -> hypothesis -> experiment -> finding -> requirement.
|
|
|
899
962
|
- Requirement: "stakeholder" (a need, in the stakeholder's words) or "solution" (what the product must do). Justified by findingIds, or, when decided elsewhere, by an origin (tender, regulation, contract, customer-need).
|
|
900
963
|
|
|
901
964
|
How to work:
|
|
902
|
-
1. Call get_workspace first: it gives product areas, products and people (for approvers).
|
|
965
|
+
1. Call get_workspace first: it gives product areas, products and people (for approvers). If an area or product you need is missing, add it with add_product_areas or add_products, after checking for an existing match.
|
|
903
966
|
2. Before creating anything, search_items for duplicates and for evidence to link. Prefer linking to existing items over creating near-duplicates.
|
|
904
967
|
3. Always link evidence: hypotheses to insights, experiments to a hypothesis, findings to experiments/hypotheses/insights, requirements to findings.
|
|
905
968
|
4. Ask the user before deleting items or approving requirements, unless they already told you to.
|
|
@@ -982,7 +1045,7 @@ var Session = class {
|
|
|
982
1045
|
const a = this.config.productAreas.find((x) => x.id === value || x.label.toLowerCase() === value.trim().toLowerCase());
|
|
983
1046
|
if (!a) {
|
|
984
1047
|
const known = this.config.productAreas.map((x) => x.label).join(", ") || "none defined";
|
|
985
|
-
throw new UserError(`Unknown product area "${value}". Areas in groundwork/config.yml: ${known}. Add it
|
|
1048
|
+
throw new UserError(`Unknown product area "${value}". Areas in groundwork/config.yml: ${known}. Add it with add_product_areas, or leave it out.`);
|
|
986
1049
|
}
|
|
987
1050
|
return a.id;
|
|
988
1051
|
}
|
|
@@ -1034,15 +1097,39 @@ function buildServer({ root }) {
|
|
|
1034
1097
|
return fail(e instanceof UserError ? e.message : `Groundwork couldn't read the project: ${e.message}`);
|
|
1035
1098
|
}
|
|
1036
1099
|
};
|
|
1037
|
-
const
|
|
1100
|
+
const refusal = (s) => {
|
|
1101
|
+
if (s.config.migrated) {
|
|
1102
|
+
return `This folder was imported into the Groundwork web app (${s.config.migrated}), which is now where changes go. Connect its MCP server instead (Groundwork \u2192 Settings \u2192 Connect an agent). These files are kept as a read-only record.`;
|
|
1103
|
+
}
|
|
1104
|
+
if (!s.canEdit()) return `${s.actor.person?.name ?? s.actor.id} is a viewer in groundwork/config.yml, so this agent can't change anything.`;
|
|
1105
|
+
return void 0;
|
|
1106
|
+
};
|
|
1107
|
+
const writeConfigOnly = (fn) => async (args) => {
|
|
1038
1108
|
try {
|
|
1039
1109
|
const s = open();
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1110
|
+
const refused = refusal(s);
|
|
1111
|
+
if (refused) return fail(refused);
|
|
1112
|
+
const { add, result } = fn(s, args);
|
|
1113
|
+
if (!isInitialized(root)) {
|
|
1114
|
+
writeConfig(root, {
|
|
1115
|
+
...s.config,
|
|
1116
|
+
productAreas: [...s.config.productAreas, ...add.productAreas ?? []],
|
|
1117
|
+
products: [...s.config.products, ...add.products ?? []]
|
|
1118
|
+
});
|
|
1119
|
+
} else if (add.productAreas?.length || add.products?.length) {
|
|
1120
|
+
appendToConfig(root, add);
|
|
1044
1121
|
}
|
|
1045
|
-
|
|
1122
|
+
return ok({ ...result, file: "groundwork/config.yml" });
|
|
1123
|
+
} catch (e) {
|
|
1124
|
+
if (e instanceof UserError || e instanceof WorkspaceError) return fail(e.message);
|
|
1125
|
+
return fail(`Groundwork couldn't save that: ${e.message}`);
|
|
1126
|
+
}
|
|
1127
|
+
};
|
|
1128
|
+
const write = (fn) => async (args) => {
|
|
1129
|
+
try {
|
|
1130
|
+
const s = open();
|
|
1131
|
+
const refused = refusal(s);
|
|
1132
|
+
if (refused) return fail(refused);
|
|
1046
1133
|
if (!isInitialized(root)) writeConfig(root, s.config);
|
|
1047
1134
|
const { state, result } = fn(s, s.loaded.items, s.ctx(), args);
|
|
1048
1135
|
const { items, renamed } = assignIds(s.loaded.items, state);
|
|
@@ -1222,10 +1309,11 @@ function buildServer({ root }) {
|
|
|
1222
1309
|
s.check(state, "insight", r.insightIds, "insightIds");
|
|
1223
1310
|
s.check(state, "hypothesis", r.hypothesisIds, "hypothesisIds");
|
|
1224
1311
|
s.checkStakeholders(state, r.stakeholderIds);
|
|
1225
|
-
|
|
1226
|
-
|
|
1312
|
+
const product = r.product && s.config.products.find((p) => p.toLowerCase() === r.product.toLowerCase());
|
|
1313
|
+
if (r.product && s.config.products.length && !product) {
|
|
1314
|
+
throw new UserError(`Unknown product "${r.product}". Products in groundwork/config.yml: ${s.config.products.join(", ")}. Add it with add_products, or leave it out.`);
|
|
1227
1315
|
}
|
|
1228
|
-
const base = { ...r, productArea: s.area(r.productArea), aiGenerated: true };
|
|
1316
|
+
const base = { ...r, ...product ? { product } : {}, productArea: s.area(r.productArea), aiGenerated: true };
|
|
1229
1317
|
if (r.findingIds.length) {
|
|
1230
1318
|
derived.push(base);
|
|
1231
1319
|
} else {
|
|
@@ -1245,6 +1333,37 @@ function buildServer({ root }) {
|
|
|
1245
1333
|
return { state: next, result: { created: created.map((x) => s.summary("requirement", x)) } };
|
|
1246
1334
|
})
|
|
1247
1335
|
);
|
|
1336
|
+
server.registerTool(
|
|
1337
|
+
"add_product_areas",
|
|
1338
|
+
{
|
|
1339
|
+
title: "Add product areas",
|
|
1340
|
+
description: "Add product areas to groundwork/config.yml so items can be tagged with them. Give labels; ids are made from them unless you pass one. Areas already there are skipped. Check get_workspace first and reuse an existing area rather than adding a near-duplicate. Can't rename or remove areas: those are edits to config.yml.",
|
|
1341
|
+
inputSchema: {
|
|
1342
|
+
areas: z4.array(
|
|
1343
|
+
z4.object({
|
|
1344
|
+
label: z4.string().trim().min(1).max(100),
|
|
1345
|
+
id: z4.string().trim().max(40).optional().describe("Optional: lowercase letters, digits and dashes. Made from the label if left out.")
|
|
1346
|
+
})
|
|
1347
|
+
).min(1).max(20)
|
|
1348
|
+
}
|
|
1349
|
+
},
|
|
1350
|
+
writeConfigOnly((s, { areas }) => {
|
|
1351
|
+
const { list, added, alreadyThere } = mergeAreas(s.config.productAreas, areas);
|
|
1352
|
+
return { add: { productAreas: added }, result: { added, alreadyThere, productAreas: list } };
|
|
1353
|
+
})
|
|
1354
|
+
);
|
|
1355
|
+
server.registerTool(
|
|
1356
|
+
"add_products",
|
|
1357
|
+
{
|
|
1358
|
+
title: "Add products",
|
|
1359
|
+
description: "Add products to groundwork/config.yml so requirements can name them. Products already there are skipped. Check get_workspace first and reuse an existing name rather than adding a near-duplicate.",
|
|
1360
|
+
inputSchema: { products: z4.array(z4.string().trim().min(1).max(100)).min(1).max(20) }
|
|
1361
|
+
},
|
|
1362
|
+
writeConfigOnly((s, { products }) => {
|
|
1363
|
+
const { list, added, alreadyThere } = mergeProducts(s.config.products, products);
|
|
1364
|
+
return { add: { products: added }, result: { added, alreadyThere, products: list } };
|
|
1365
|
+
})
|
|
1366
|
+
);
|
|
1248
1367
|
server.registerTool(
|
|
1249
1368
|
"update_item",
|
|
1250
1369
|
{
|
|
@@ -1509,6 +1628,7 @@ export {
|
|
|
1509
1628
|
ConfigError,
|
|
1510
1629
|
readConfig,
|
|
1511
1630
|
writeConfig,
|
|
1631
|
+
appendToConfig,
|
|
1512
1632
|
resolveActor,
|
|
1513
1633
|
COLLECTIONS,
|
|
1514
1634
|
parseItem,
|
|
@@ -1521,4 +1641,4 @@ export {
|
|
|
1521
1641
|
outgoing,
|
|
1522
1642
|
buildServer
|
|
1523
1643
|
};
|
|
1524
|
-
//# sourceMappingURL=chunk-
|
|
1644
|
+
//# sourceMappingURL=chunk-3YZLRKZH.js.map
|