create-academic-research 0.1.11 → 0.1.13
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 +70 -40
- package/dist/src/agents.js +1 -1
- package/dist/src/capabilities.js +7 -7
- package/dist/src/cli.js +13 -13
- package/dist/src/project.js +42 -0
- package/package.json +10 -3
- package/template/README.md +22 -22
- package/template/docs/agent/mcp-client-setup.md +7 -7
- package/template/docs/agent/mcp-setup.md +4 -5
- package/template/docs/getting-started.md +10 -10
- package/template/package.json +25 -13
package/README.md
CHANGED
|
@@ -1,8 +1,19 @@
|
|
|
1
1
|
# Create Academic Research
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/create-academic-research)
|
|
4
|
+
[](https://github.com/VincenzoImp/create-academic-research/actions/workflows/validate.yml)
|
|
5
|
+
[](https://github.com/VincenzoImp/create-academic-research/actions/workflows/release.yml)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
3
8
|
Create agent-ready academic research repositories with one command.
|
|
4
9
|
|
|
5
|
-
|
|
10
|
+
`create-academic-research` scaffolds a serious research workspace: source
|
|
11
|
+
ledgers, SOTA files, citation audit tables, experiment records, reproducibility
|
|
12
|
+
docs, durable wiki/log memory, project-local skills, and MCP setup for scholarly
|
|
13
|
+
search. The template is discipline-general and especially strong for computer
|
|
14
|
+
science research.
|
|
15
|
+
|
|
16
|
+
## Quickstart
|
|
6
17
|
|
|
7
18
|
```bash
|
|
8
19
|
npm create academic-research@latest my-project
|
|
@@ -23,9 +34,16 @@ From GitHub:
|
|
|
23
34
|
npx --yes github:VincenzoImp/create-academic-research my-project
|
|
24
35
|
```
|
|
25
36
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
37
|
+
## What It Creates
|
|
38
|
+
|
|
39
|
+
| Area | Generated Support |
|
|
40
|
+
|---|---|
|
|
41
|
+
| Sources | PDFs, derived Markdown, metadata, BibTeX, conversion ledger, source ledger. |
|
|
42
|
+
| Literature Review | Search strategy, screening decisions, literature matrix, SOTA synthesis, gaps, PRISMA flow. |
|
|
43
|
+
| Agent Memory | `AGENTS.md`, capability profile, MCP setup docs, generated MCP snippets, wiki index/log/templates. |
|
|
44
|
+
| Reproducibility | Python package scaffold, tests, experiment registry, output folders, artifact checklist. |
|
|
45
|
+
| Skills | Project-local installation flow for `VincenzoImp/academic-research-skills`. |
|
|
46
|
+
| MCP | Conservative default records for scholarly discovery plus documented optional integrations. |
|
|
29
47
|
|
|
30
48
|
The wizard is discipline-general: it creates a clean structure for academic
|
|
31
49
|
research projects in any field. Its companion skill stack gives first-class
|
|
@@ -37,9 +55,18 @@ The generated repository is agent-neutral. By default the wizard records
|
|
|
37
55
|
`agent: universal`, installs one shared project-local `.agents/skills` copy,
|
|
38
56
|
and writes generic MCP snippets. Use `--agent <id>` only when you want to force
|
|
39
57
|
a specific target recognized by the `skills` CLI. Run
|
|
40
|
-
`
|
|
58
|
+
`npm run agents:list` inside a generated project to see every
|
|
41
59
|
supported target and alias.
|
|
42
60
|
|
|
61
|
+
## When To Use It
|
|
62
|
+
|
|
63
|
+
Use this when starting or cleaning up an academic research project that needs
|
|
64
|
+
evidence tracking, literature-review discipline, repeatable experiments, paper
|
|
65
|
+
writing support, or LLM-agent collaboration. It is not a paper generator and it
|
|
66
|
+
does not replace methodological judgment; it gives the repository enough
|
|
67
|
+
structure for serious research work to compound instead of scattering across
|
|
68
|
+
chat history, notebooks, PDFs, and ad hoc folders.
|
|
69
|
+
|
|
43
70
|
## Default Experience
|
|
44
71
|
|
|
45
72
|
By default, the wizard:
|
|
@@ -86,35 +113,38 @@ npx create-academic-research@latest my-project --yes --no-install-skills
|
|
|
86
113
|
Inside a generated project:
|
|
87
114
|
|
|
88
115
|
```bash
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
+
npm run doctor
|
|
117
|
+
npm run setup
|
|
118
|
+
npm run rename -- --title "New Title" --slug new-title --package new_title
|
|
119
|
+
npm run agents:list
|
|
120
|
+
npm run skills:presets
|
|
121
|
+
npm run skills:install
|
|
122
|
+
npm run skills:install -- --preset enhanced
|
|
123
|
+
npm run skills:install -- source-ingestion sota-literature-review
|
|
124
|
+
npm run skills:list
|
|
125
|
+
npm run skills:status
|
|
126
|
+
npm run skills:remove -- source-ingestion
|
|
127
|
+
npm run skills:uninstall -- source-ingestion
|
|
128
|
+
npm run skills:update
|
|
129
|
+
npm run mcp:list
|
|
130
|
+
npm run mcp:enabled
|
|
131
|
+
npm run mcp:available
|
|
132
|
+
npm run mcp:commands -- arxiv
|
|
133
|
+
npm run mcp:env -- openalex semantic-scholar zotero
|
|
134
|
+
npm run mcp:env -- --dotenv --all > .env.example
|
|
135
|
+
npm run mcp:dotenv
|
|
136
|
+
npm run mcp:enable -- arxiv dblp
|
|
137
|
+
npm run mcp:disable -- arxiv
|
|
138
|
+
npm run mcp:install -- arxiv
|
|
139
|
+
npm run mcp:uninstall -- arxiv
|
|
140
|
+
npm run mcp:smoke -- --env-file .env.local
|
|
141
|
+
npm run mcp:doctor -- --env-file .env.local
|
|
142
|
+
npm run mcp:probe -- arxiv --timeout-ms 5000
|
|
116
143
|
```
|
|
117
144
|
|
|
145
|
+
For direct one-off invocation without the generated package scripts, use
|
|
146
|
+
`npx --yes --package create-academic-research@latest academic-research <command>`.
|
|
147
|
+
|
|
118
148
|
## Command Model
|
|
119
149
|
|
|
120
150
|
`academic-research setup` is a non-destructive onboarding status command. It
|
|
@@ -162,7 +192,7 @@ Those skills are portable `SKILL.md` instructions, but they require an
|
|
|
162
192
|
agent/runtime that can load skills or include the relevant instructions in
|
|
163
193
|
context. They are not automatic capabilities of every raw model API.
|
|
164
194
|
Use `--agent <id>` for explicit setup with any id from
|
|
165
|
-
`
|
|
195
|
+
`npm run agents:list`. The shorthand `--agent claude` is normalized
|
|
166
196
|
to the supported `claude-code` target.
|
|
167
197
|
Avoid `--agent auto` for unattended setup: the upstream `skills` CLI may expand
|
|
168
198
|
it to every agent it detects on the machine.
|
|
@@ -181,9 +211,9 @@ Preset intent:
|
|
|
181
211
|
MCP defaults are intentionally conservative. Semantic Scholar, OpenAlex,
|
|
182
212
|
Zotero, Overleaf, Crossref, and fallback aggregators are useful, but they need
|
|
183
213
|
API keys, local apps, manual setup, or source-policy review. Enable them with
|
|
184
|
-
`
|
|
185
|
-
`docs/agent/mcp-setup.md`, use `
|
|
186
|
-
|
|
214
|
+
`npm run mcp:enable -- <server>` after reading
|
|
215
|
+
`docs/agent/mcp-setup.md`, use `npm run mcp:env -- <server>` to see runtime
|
|
216
|
+
prerequisites, then run `npm run mcp:doctor`.
|
|
187
217
|
|
|
188
218
|
The MCP catalog distinguishes local runtime adapters from hosted endpoints and
|
|
189
219
|
manual integrations. arXiv and DBLP are low-friction local `uvx` runtimes.
|
|
@@ -198,8 +228,8 @@ until a project explicitly needs them.
|
|
|
198
228
|
|
|
199
229
|
Generated projects include a committed `.env.example` with empty MCP variables
|
|
200
230
|
and ignore filled `.env` or `.env.local` files. Regenerate the example with
|
|
201
|
-
`
|
|
202
|
-
|
|
231
|
+
`npm run mcp:dotenv`. `mcp doctor`, `mcp smoke`, and `mcp probe` check the
|
|
232
|
+
current process environment unless you explicitly pass
|
|
203
233
|
`--env-file .env.local`.
|
|
204
234
|
|
|
205
235
|
Generated MCP snippets are project documentation and client-ready config, not
|
|
@@ -229,8 +259,8 @@ Releases are tag-driven. Update `package.json` and `package-lock.json`, commit
|
|
|
229
259
|
the change, create `vX.Y.Z`, and push the tag:
|
|
230
260
|
|
|
231
261
|
```bash
|
|
232
|
-
git tag -a
|
|
233
|
-
git push origin main
|
|
262
|
+
git tag -a vX.Y.Z -m "vX.Y.Z"
|
|
263
|
+
git push origin main vX.Y.Z
|
|
234
264
|
```
|
|
235
265
|
|
|
236
266
|
Once the GitHub repository is public, the release workflow validates the tag
|
package/dist/src/agents.js
CHANGED
|
@@ -79,7 +79,7 @@ export function assertKnownAgentTarget(agent) {
|
|
|
79
79
|
throw new Error([
|
|
80
80
|
`unknown agent target: ${value}`,
|
|
81
81
|
`Use ${DEFAULT_AGENT}, ${AUTO_AGENT}, or one supported skills.sh agent id.`,
|
|
82
|
-
"List targets with: npx
|
|
82
|
+
"List targets with: npx --yes --package create-academic-research@latest academic-research agents list",
|
|
83
83
|
`Supported ids: ${specificAgentTargets().join(", ")}`,
|
|
84
84
|
`Aliases: ${formatAgentAliasesInline()}`
|
|
85
85
|
].join("\n"));
|
package/dist/src/capabilities.js
CHANGED
|
@@ -331,12 +331,12 @@ async function writeCapabilityProfile(root, state) {
|
|
|
331
331
|
"",
|
|
332
332
|
"## Skills",
|
|
333
333
|
"",
|
|
334
|
-
`- Install with: \`
|
|
335
|
-
"- Install selected skills with: `
|
|
336
|
-
"- List installed with: `
|
|
337
|
-
"- List presets with: `
|
|
338
|
-
"- Remove with: `
|
|
339
|
-
"- Update with: `
|
|
334
|
+
`- Install with: \`npm run skills:install -- --preset ${state.preset ?? "default"}\``,
|
|
335
|
+
"- Install selected skills with: `npm run skills:install -- <skill-id> [...]`",
|
|
336
|
+
"- List installed with: `npm run skills:list`",
|
|
337
|
+
"- List presets with: `npm run skills:presets`",
|
|
338
|
+
"- Remove with: `npm run skills:remove -- <skill>`",
|
|
339
|
+
"- Update with: `npm run skills:update`",
|
|
340
340
|
"",
|
|
341
341
|
"## MCP Servers",
|
|
342
342
|
""
|
|
@@ -383,7 +383,7 @@ async function writeMcpSetup(root, state) {
|
|
|
383
383
|
lines.push(`- \`${name}\` (${status}, ${server.readiness}, ${server.priority}): ${server.source_need}`, ` - Source: \`${server.source}\``, ` - Execution mode: \`${server.execution_mode}\``, ...(server.hosted_url ? [` - Hosted endpoint: <${server.hosted_url}>`] : []), ...server.setup_commands.map((command) => ` - Setup command: \`${command}\``));
|
|
384
384
|
appendMcpPrerequisiteLines(lines, server.required_env, server.recommended_env, server.local_service);
|
|
385
385
|
}
|
|
386
|
-
lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Print a dotenv-style reference with `
|
|
386
|
+
lines.push("", "## Operating Rules", "", "- Use `.env.example` as a committed reference and put filled secrets in `.env.local`, your shell, or your MCP client secret store.", "- Print a dotenv-style reference with `npm run mcp:env -- --dotenv --all`.", "- Regenerate a dotenv-style reference with `npm run mcp:dotenv`.", "- Pass `--env-file .env.local` to `mcp doctor`, `mcp smoke`, or `mcp probe` when you want the CLI to read explicit local secrets.", "- Keep secrets in your shell, MCP client secret store, or local untracked files; do not commit tokens or API keys.", "- Prefer the smallest enabled MCP set that covers the current research question.", "- Treat MCP output as retrieval metadata. Promote claims into repository source records only after source ingestion and citation audit.", "- Run `npm run mcp:doctor` after changing MCP records or environment variables.", "- Run `npm run mcp:probe -- <server>` only when you intentionally want to start selected MCP server processes.", "");
|
|
387
387
|
await mkdir(join(root, "docs/agent"), { recursive: true });
|
|
388
388
|
await writeFile(join(root, "docs/agent/mcp-setup.md"), lines.join("\n"), "utf8");
|
|
389
389
|
}
|
package/dist/src/cli.js
CHANGED
|
@@ -94,7 +94,7 @@ async function createMain(argv) {
|
|
|
94
94
|
await installMcpTools(result.root, presetMcpServers(answers.preset));
|
|
95
95
|
}
|
|
96
96
|
console.log(`Created ${result.slug} at ${result.root}`);
|
|
97
|
-
console.log("Next: cd into the project and run `
|
|
97
|
+
console.log("Next: cd into the project and run `npm run doctor`.");
|
|
98
98
|
return 0;
|
|
99
99
|
}
|
|
100
100
|
async function askInteractiveCreateOptions(defaults, locks) {
|
|
@@ -167,14 +167,14 @@ async function setupCommand(argv) {
|
|
|
167
167
|
}
|
|
168
168
|
console.log("");
|
|
169
169
|
console.log("Next Commands");
|
|
170
|
-
console.log(`
|
|
171
|
-
console.log("
|
|
172
|
-
console.log("
|
|
173
|
-
console.log("
|
|
174
|
-
console.log("
|
|
175
|
-
console.log("
|
|
176
|
-
console.log("
|
|
177
|
-
console.log("
|
|
170
|
+
console.log(`npm run skills:install -- --preset ${state.preset}`);
|
|
171
|
+
console.log("npm run skills:status");
|
|
172
|
+
console.log("npm run mcp:list");
|
|
173
|
+
console.log("npm run mcp:env");
|
|
174
|
+
console.log("npm run mcp:dotenv");
|
|
175
|
+
console.log("npm run mcp:smoke");
|
|
176
|
+
console.log("npm run mcp:probe -- arxiv");
|
|
177
|
+
console.log("npm run doctor");
|
|
178
178
|
return project.ok ? 0 : 1;
|
|
179
179
|
}
|
|
180
180
|
async function renameCommand(argv) {
|
|
@@ -579,10 +579,10 @@ export function formatInteractiveCreateGuide() {
|
|
|
579
579
|
" default enables only low-friction arXiv; credentialed/local services are opt-in.",
|
|
580
580
|
" MCP installers are optional and run only finite installer commands.",
|
|
581
581
|
" MCP execution modes are explicit: uvx-runtime, npx-runtime, local-service, manual, or fallback.",
|
|
582
|
-
" Use `
|
|
583
|
-
" Use `
|
|
584
|
-
" Use `
|
|
585
|
-
" Use `
|
|
582
|
+
" Use `npm run mcp:env -- <server>` to inspect env vars and local prerequisites.",
|
|
583
|
+
" Use `npm run mcp:env -- --dotenv --all` to print a committed env example.",
|
|
584
|
+
" Use `npm run mcp:dotenv` to regenerate a committed env example.",
|
|
585
|
+
" Use `npm run mcp:doctor -- --env-file .env.local` to check explicit local secrets.",
|
|
586
586
|
""
|
|
587
587
|
].join("\n");
|
|
588
588
|
}
|
package/dist/src/project.js
CHANGED
|
@@ -223,12 +223,54 @@ async function writeGeneratedPackageJson(root, { slug, preserveExistingSpec = fa
|
|
|
223
223
|
(preserveExistingSpec ? existingSpec : undefined) ??
|
|
224
224
|
await currentPackageVersion();
|
|
225
225
|
data.name = slug;
|
|
226
|
+
data.scripts = {
|
|
227
|
+
...(data.scripts ?? {}),
|
|
228
|
+
...generatedLifecycleScripts(packageSpec)
|
|
229
|
+
};
|
|
226
230
|
data.devDependencies = {
|
|
227
231
|
...(data.devDependencies ?? {}),
|
|
228
232
|
"create-academic-research": packageSpec
|
|
229
233
|
};
|
|
230
234
|
await writeJson(path, data);
|
|
231
235
|
}
|
|
236
|
+
function generatedLifecycleScripts(packageSpec) {
|
|
237
|
+
const command = `npm exec --yes --package=${lifecyclePackageSpec(packageSpec)} -- academic-research`;
|
|
238
|
+
return {
|
|
239
|
+
doctor: `${command} doctor`,
|
|
240
|
+
setup: `${command} setup`,
|
|
241
|
+
rename: `${command} rename`,
|
|
242
|
+
"agents:list": `${command} agents list`,
|
|
243
|
+
"skills:install": `${command} skills install`,
|
|
244
|
+
"skills:list": `${command} skills list`,
|
|
245
|
+
"skills:status": `${command} skills status`,
|
|
246
|
+
"skills:presets": `${command} skills presets`,
|
|
247
|
+
"skills:remove": `${command} skills remove`,
|
|
248
|
+
"skills:uninstall": `${command} skills uninstall`,
|
|
249
|
+
"skills:update": `${command} skills update`,
|
|
250
|
+
"mcp:list": `${command} mcp list`,
|
|
251
|
+
"mcp:enabled": `${command} mcp enabled`,
|
|
252
|
+
"mcp:available": `${command} mcp available`,
|
|
253
|
+
"mcp:commands": `${command} mcp commands`,
|
|
254
|
+
"mcp:env": `${command} mcp env`,
|
|
255
|
+
"mcp:dotenv": `${command} mcp env --write .env.example --all`,
|
|
256
|
+
"mcp:enable": `${command} mcp enable`,
|
|
257
|
+
"mcp:disable": `${command} mcp disable`,
|
|
258
|
+
"mcp:install": `${command} mcp install`,
|
|
259
|
+
"mcp:uninstall": `${command} mcp uninstall`,
|
|
260
|
+
"mcp:smoke": `${command} mcp smoke`,
|
|
261
|
+
"mcp:doctor": `${command} mcp doctor`,
|
|
262
|
+
"mcp:probe": `${command} mcp probe`
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
function lifecyclePackageSpec(packageSpec) {
|
|
266
|
+
if (packageSpec === "create-academic-research" || packageSpec.startsWith("create-academic-research@")) {
|
|
267
|
+
return packageSpec;
|
|
268
|
+
}
|
|
269
|
+
if (/^(file:|github:|git[+:]|https?:)/.test(packageSpec) || packageSpec.includes("/")) {
|
|
270
|
+
return packageSpec;
|
|
271
|
+
}
|
|
272
|
+
return `create-academic-research@${packageSpec}`;
|
|
273
|
+
}
|
|
232
274
|
async function writeGeneratedGitignore(root) {
|
|
233
275
|
const source = join(root, "_gitignore");
|
|
234
276
|
if (await exists(source)) {
|
package/package.json
CHANGED
|
@@ -1,17 +1,24 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-academic-research",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.1.13",
|
|
4
|
+
"description": "Scaffold agent-ready academic research repositories with SOTA, source ledgers, wiki memory, MCP setup, and project-local skills.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"author": "Vincenzo Imperati",
|
|
8
8
|
"keywords": [
|
|
9
9
|
"academic-research",
|
|
10
|
+
"academic-writing",
|
|
11
|
+
"arxiv",
|
|
12
|
+
"citation-management",
|
|
10
13
|
"research-project",
|
|
14
|
+
"research-scaffold",
|
|
11
15
|
"agent-skills",
|
|
16
|
+
"llm-agents",
|
|
12
17
|
"mcp",
|
|
13
18
|
"literature-review",
|
|
14
|
-
"
|
|
19
|
+
"open-science",
|
|
20
|
+
"reproducibility",
|
|
21
|
+
"sota"
|
|
15
22
|
],
|
|
16
23
|
"repository": {
|
|
17
24
|
"type": "git",
|
package/template/README.md
CHANGED
|
@@ -30,7 +30,7 @@ python3.11 -m venv .venv
|
|
|
30
30
|
source .venv/bin/activate
|
|
31
31
|
python -m pip install --upgrade pip
|
|
32
32
|
python -m pip install -e ".[dev]"
|
|
33
|
-
|
|
33
|
+
npm run doctor
|
|
34
34
|
```
|
|
35
35
|
|
|
36
36
|
## Core Folders
|
|
@@ -53,23 +53,23 @@ npx academic-research doctor
|
|
|
53
53
|
Project-local skills and MCP records are managed with:
|
|
54
54
|
|
|
55
55
|
```bash
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
56
|
+
npm run skills:presets
|
|
57
|
+
npm run agents:list
|
|
58
|
+
npm run skills:install
|
|
59
|
+
npm run skills:install -- --preset enhanced
|
|
60
|
+
npm run skills:install -- source-ingestion sota-literature-review
|
|
61
|
+
npm run skills:list
|
|
62
|
+
npm run skills:status
|
|
63
|
+
npm run setup
|
|
64
|
+
npm run mcp:dotenv
|
|
65
|
+
npm run mcp:list
|
|
66
|
+
npm run mcp:env -- openalex semantic-scholar zotero
|
|
67
|
+
npm run mcp:enable -- arxiv dblp
|
|
68
|
+
npm run mcp:commands -- arxiv
|
|
69
|
+
npm run mcp:install -- arxiv
|
|
70
|
+
npm run mcp:smoke -- --env-file .env.local
|
|
71
|
+
npm run mcp:doctor -- --env-file .env.local
|
|
72
|
+
npm run mcp:probe -- arxiv --timeout-ms 5000
|
|
73
73
|
```
|
|
74
74
|
|
|
75
75
|
`skills list` reports installed project-local skills. `skills presets` reports
|
|
@@ -81,10 +81,10 @@ commands; runtime-only `uvx`/`npx` MCP servers may have no install step and are
|
|
|
81
81
|
started later by the MCP client.
|
|
82
82
|
|
|
83
83
|
`.env.example` is the committed MCP environment reference. Regenerate it with
|
|
84
|
-
`
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
84
|
+
`npm run mcp:dotenv`. Copy it to `.env.local`, your shell profile, or your MCP
|
|
85
|
+
client secret store when secrets are needed. Filled `.env` files are ignored by
|
|
86
|
+
git. `mcp doctor` checks the current process environment unless you explicitly
|
|
87
|
+
pass `--env-file .env.local`.
|
|
88
88
|
|
|
89
89
|
`setup` prints the current project capability state, installed skill counts,
|
|
90
90
|
enabled MCP records, and the next onboarding commands without changing files.
|
|
@@ -19,7 +19,7 @@ store.
|
|
|
19
19
|
Regenerate the committed reference from the current MCP catalog with:
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
|
|
22
|
+
npm run mcp:dotenv
|
|
23
23
|
```
|
|
24
24
|
|
|
25
25
|
Create a private local file when needed:
|
|
@@ -33,9 +33,9 @@ Do not commit filled `.env`, `.env.local`, tokens, cookies, or browser sessions.
|
|
|
33
33
|
environment unless you explicitly pass `--env-file .env.local`.
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
36
|
+
npm run mcp:doctor -- --env-file .env.local
|
|
37
|
+
npm run mcp:smoke -- --env-file .env.local
|
|
38
|
+
npm run mcp:probe -- arxiv --timeout-ms 5000
|
|
39
39
|
```
|
|
40
40
|
|
|
41
41
|
## Client Notes
|
|
@@ -57,10 +57,10 @@ required variables are already exported.
|
|
|
57
57
|
## Workflow
|
|
58
58
|
|
|
59
59
|
1. Enable only the MCP servers needed for the current research task.
|
|
60
|
-
2. Inspect prerequisites with `
|
|
60
|
+
2. Inspect prerequisites with `npm run mcp:env -- <server>`.
|
|
61
61
|
3. Put required secrets in the MCP client secret store, shell, or `.env.local`.
|
|
62
|
-
4. Run `
|
|
63
|
-
5. Run `
|
|
62
|
+
4. Run `npm run mcp:smoke -- --env-file .env.local`.
|
|
63
|
+
5. Run `npm run mcp:probe -- <server>` only when you want to start
|
|
64
64
|
the server and verify a real stdio handshake.
|
|
65
65
|
6. Load the generated snippet in the MCP client.
|
|
66
66
|
7. Treat MCP output as retrieval metadata until it is ingested into repository
|
|
@@ -5,9 +5,8 @@ and known risks here.
|
|
|
5
5
|
|
|
6
6
|
Use `.env.example` as the committed environment reference. Put filled values in
|
|
7
7
|
`.env.local`, the shell, or the MCP client secret store. Regenerate the example
|
|
8
|
-
with `
|
|
8
|
+
with `npm run mcp:dotenv`.
|
|
9
9
|
|
|
10
|
-
Use `
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
stdio handshake.
|
|
10
|
+
Use `npm run mcp:doctor -- --env-file .env.local` when you want the CLI to read
|
|
11
|
+
an explicit local env file. Use `npm run mcp:probe -- <server>` only when you
|
|
12
|
+
want to start a selected MCP server and verify a real stdio handshake.
|
|
@@ -6,8 +6,8 @@ Use this path for the first working session in a new research repository.
|
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
npm install
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
npm run doctor
|
|
10
|
+
npm run setup
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
`doctor` checks required files and structural contracts. `setup` prints the
|
|
@@ -19,15 +19,15 @@ commands without changing files.
|
|
|
19
19
|
Install the default academic research skill package:
|
|
20
20
|
|
|
21
21
|
```bash
|
|
22
|
-
|
|
23
|
-
|
|
22
|
+
npm run skills:install
|
|
23
|
+
npm run skills:status
|
|
24
24
|
```
|
|
25
25
|
|
|
26
26
|
Use `enhanced` only when the project also needs complementary development,
|
|
27
27
|
document, frontend, testing, and conversion skills:
|
|
28
28
|
|
|
29
29
|
```bash
|
|
30
|
-
|
|
30
|
+
npm run skills:install -- --preset enhanced
|
|
31
31
|
```
|
|
32
32
|
|
|
33
33
|
## 3. Prepare MCP Environment
|
|
@@ -36,18 +36,18 @@ Keep `.env.example` committed and empty of real secrets. Put filled values in
|
|
|
36
36
|
`.env.local`, your shell, or your MCP client secret store.
|
|
37
37
|
|
|
38
38
|
```bash
|
|
39
|
-
|
|
39
|
+
npm run mcp:dotenv
|
|
40
40
|
cp .env.example .env.local
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
npm run mcp:env -- openalex semantic-scholar zotero
|
|
42
|
+
npm run mcp:doctor -- --env-file .env.local
|
|
43
43
|
```
|
|
44
44
|
|
|
45
45
|
`mcp smoke` is a non-launching readiness check. `mcp probe` is opt-in and starts
|
|
46
46
|
MCP processes for a real stdio handshake.
|
|
47
47
|
|
|
48
48
|
```bash
|
|
49
|
-
|
|
50
|
-
|
|
49
|
+
npm run mcp:smoke -- --env-file .env.local
|
|
50
|
+
npm run mcp:probe -- arxiv --timeout-ms 5000
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
## 4. Start Source Work
|
package/template/package.json
CHANGED
|
@@ -3,20 +3,32 @@
|
|
|
3
3
|
"private": true,
|
|
4
4
|
"type": "module",
|
|
5
5
|
"scripts": {
|
|
6
|
-
"doctor": "academic-research doctor",
|
|
7
|
-
"setup": "academic-research setup",
|
|
8
|
-
"
|
|
9
|
-
"
|
|
10
|
-
"skills:
|
|
11
|
-
"
|
|
12
|
-
"
|
|
13
|
-
"
|
|
14
|
-
"
|
|
15
|
-
"
|
|
16
|
-
"
|
|
17
|
-
"mcp:
|
|
6
|
+
"doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research doctor",
|
|
7
|
+
"setup": "npm exec --yes --package=create-academic-research@latest -- academic-research setup",
|
|
8
|
+
"rename": "npm exec --yes --package=create-academic-research@latest -- academic-research rename",
|
|
9
|
+
"agents:list": "npm exec --yes --package=create-academic-research@latest -- academic-research agents list",
|
|
10
|
+
"skills:install": "npm exec --yes --package=create-academic-research@latest -- academic-research skills install",
|
|
11
|
+
"skills:list": "npm exec --yes --package=create-academic-research@latest -- academic-research skills list",
|
|
12
|
+
"skills:status": "npm exec --yes --package=create-academic-research@latest -- academic-research skills status",
|
|
13
|
+
"skills:presets": "npm exec --yes --package=create-academic-research@latest -- academic-research skills presets",
|
|
14
|
+
"skills:remove": "npm exec --yes --package=create-academic-research@latest -- academic-research skills remove",
|
|
15
|
+
"skills:uninstall": "npm exec --yes --package=create-academic-research@latest -- academic-research skills uninstall",
|
|
16
|
+
"skills:update": "npm exec --yes --package=create-academic-research@latest -- academic-research skills update",
|
|
17
|
+
"mcp:list": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp list",
|
|
18
|
+
"mcp:enabled": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp enabled",
|
|
19
|
+
"mcp:available": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp available",
|
|
20
|
+
"mcp:commands": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp commands",
|
|
21
|
+
"mcp:env": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp env",
|
|
22
|
+
"mcp:dotenv": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp env --write .env.example --all",
|
|
23
|
+
"mcp:enable": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp enable",
|
|
24
|
+
"mcp:disable": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp disable",
|
|
25
|
+
"mcp:install": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp install",
|
|
26
|
+
"mcp:uninstall": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp uninstall",
|
|
27
|
+
"mcp:smoke": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp smoke",
|
|
28
|
+
"mcp:doctor": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp doctor",
|
|
29
|
+
"mcp:probe": "npm exec --yes --package=create-academic-research@latest -- academic-research mcp probe"
|
|
18
30
|
},
|
|
19
31
|
"devDependencies": {
|
|
20
|
-
"create-academic-research": "0.1.
|
|
32
|
+
"create-academic-research": "0.1.13"
|
|
21
33
|
}
|
|
22
34
|
}
|