@softpractice/softpractice-cli 0.2.1 → 0.2.2
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 +78 -84
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -91,6 +91,8 @@ softpractice update
|
|
|
91
91
|
| `softpractice open` | Open the task, material, or latest result in the browser |
|
|
92
92
|
| `softpractice mcp` | Run the MCP server for Claude Code, Codex, Claude Desktop, and other agents |
|
|
93
93
|
| `softpractice mcp setup codex-desktop` | Configure MCP for Codex Desktop without installing Codex CLI |
|
|
94
|
+
| `softpractice mcp status` | Check the running server and its project |
|
|
95
|
+
| `softpractice mcp remove codex-desktop` | Remove the connection from Codex settings |
|
|
94
96
|
| `softpractice project restore` | Restore a project from the latest usable revision |
|
|
95
97
|
|
|
96
98
|
Run `softpractice help <command>` for detailed help.
|
|
@@ -149,128 +151,120 @@ never replaces them, and they are not part of your submission.
|
|
|
149
151
|
|
|
150
152
|
`softpractice mcp` connects a coding agent to your SoftPractice lesson:
|
|
151
153
|
reading the task and material, running public checks, submitting a commit, and
|
|
152
|
-
reading the evaluation.
|
|
153
|
-
starts the process and communicates with it. No server URL or listening port
|
|
154
|
-
is needed.
|
|
154
|
+
reading the evaluation.
|
|
155
155
|
|
|
156
|
-
###
|
|
156
|
+
### Configure once, from any folder
|
|
157
157
|
|
|
158
|
-
Install the CLI (see [Install](#install)),
|
|
159
|
-
|
|
160
|
-
`softpractice project restore`:
|
|
158
|
+
Install the CLI (see [Install](#install)), then configure your desktop client.
|
|
159
|
+
You do not need a lesson project yet:
|
|
161
160
|
|
|
162
161
|
```bash
|
|
163
|
-
softpractice
|
|
164
|
-
|
|
165
|
-
softpractice
|
|
162
|
+
softpractice mcp setup claude-desktop
|
|
163
|
+
# or
|
|
164
|
+
softpractice mcp setup codex-desktop
|
|
166
165
|
```
|
|
167
166
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
167
|
+
Setup registers the CLI's absolute executable path and `mcp connect` as the
|
|
168
|
+
launch arguments. It preserves other settings and saves the previous file as
|
|
169
|
+
`.bak`. Claude Desktop uses `claude_desktop_config.json`; on Windows, setup
|
|
170
|
+
also finds the configuration used by the Microsoft Store version. Codex uses
|
|
171
|
+
`~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and a tool timeout of
|
|
172
|
+
180 seconds. Codex Desktop, CLI, and the IDE extension share these settings.
|
|
173
|
+
No separate Codex CLI installation is needed for desktop setup.
|
|
172
174
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
cannot find `softpractice` on `PATH`, use the executable's full path as the
|
|
177
|
-
command. The client must run on the computer where the CLI and project exist.
|
|
175
|
+
For manual configuration, append `--print` to either setup command. It prints
|
|
176
|
+
the JSON or TOML entry without writing settings. Replace an existing
|
|
177
|
+
`softpractice` entry rather than adding a duplicate.
|
|
178
178
|
|
|
179
|
-
###
|
|
179
|
+
### Start the lesson server
|
|
180
180
|
|
|
181
|
-
|
|
181
|
+
Sign in, then start the server for a Git project downloaded with
|
|
182
|
+
`softpractice starter` or restored with `softpractice project restore`:
|
|
182
183
|
|
|
183
184
|
```bash
|
|
184
|
-
softpractice
|
|
185
|
+
softpractice login
|
|
186
|
+
cd /path/to/your/lesson-project
|
|
187
|
+
softpractice mcp
|
|
185
188
|
```
|
|
186
189
|
|
|
187
|
-
|
|
188
|
-
file, `claude_desktop_config.json`, with absolute paths to the program and the
|
|
189
|
-
project: Claude Desktop does not see the `PATH` from your terminal profile and
|
|
190
|
-
does not start the server in your project folder. Other servers and app
|
|
191
|
-
settings in the file are kept; the previous file is saved next to it as
|
|
192
|
-
`claude_desktop_config.json.bak`. On Windows, the command also finds the file
|
|
193
|
-
that the Microsoft Store version of the app actually reads.
|
|
194
|
-
|
|
195
|
-
Then quit Claude Desktop completely, not just its window, and start it again.
|
|
196
|
-
The `softpractice` tools appear in the chat's tools menu. When you switch to
|
|
197
|
-
another lesson project, run the command again in its folder.
|
|
198
|
-
|
|
199
|
-
To configure the app manually, print the entry and add it to `mcpServers` in
|
|
200
|
-
the file opened by **Settings → Developer → Edit Config**, keeping the servers
|
|
201
|
-
already configured:
|
|
190
|
+
Or start from any folder with an explicit project:
|
|
202
191
|
|
|
203
192
|
```bash
|
|
204
|
-
softpractice mcp
|
|
193
|
+
softpractice mcp --project /path/to/your/lesson-project
|
|
205
194
|
```
|
|
206
195
|
|
|
207
|
-
|
|
196
|
+
Keep this terminal open. The server validates the Git repository and
|
|
197
|
+
SoftPractice project link before accepting connections. It uses the CLI's
|
|
198
|
+
saved sign-in; it never opens a sign-in flow itself.
|
|
208
199
|
|
|
209
|
-
|
|
200
|
+
Start the server before restarting the desktop client. The client's stdio
|
|
201
|
+
bridge, `softpractice mcp connect`, forwards MCP messages to the running
|
|
202
|
+
server on `127.0.0.1:39473`. Connections require a random per-run key saved in
|
|
203
|
+
the CLI's user configuration folder. Both processes must run on the same
|
|
204
|
+
computer under the same user and use the same `SOFTPRACTICE_CONFIG_DIR` if
|
|
205
|
+
that environment variable is set. This address is not an HTTP URL.
|
|
210
206
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
207
|
+
Only one lesson server can run on this computer at a time. To switch projects,
|
|
208
|
+
stop it with Ctrl+C, start it in the other lesson folder, and reconnect the
|
|
209
|
+
client's MCP connection (or restart the client). Setup does not need to be
|
|
210
|
+
repeated. If the server is offline, the bridge prints the startup command to
|
|
211
|
+
stderr and exits; start the server and reconnect.
|
|
215
212
|
|
|
216
|
-
|
|
217
|
-
Code in the same folder; use `/mcp` to check the connection. See the
|
|
218
|
-
[Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).
|
|
213
|
+
### Claude Code and Codex CLI
|
|
219
214
|
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
From the lesson project folder:
|
|
215
|
+
To use the same manually started server:
|
|
223
216
|
|
|
224
217
|
```bash
|
|
225
|
-
softpractice mcp
|
|
218
|
+
claude mcp add --transport stdio --scope user softpractice -- softpractice mcp connect
|
|
219
|
+
# or, if Codex Desktop setup has not already configured it:
|
|
220
|
+
codex mcp add softpractice -- softpractice mcp connect
|
|
226
221
|
```
|
|
227
222
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
and
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
223
|
+
If the client cannot find `softpractice`, use the executable's full path.
|
|
224
|
+
See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
|
|
225
|
+
and [Codex MCP documentation](https://developers.openai.com/codex/mcp).
|
|
226
|
+
|
|
227
|
+
`softpractice mcp` always starts the local server, including with redirected
|
|
228
|
+
stdin or in the background. Only server startup selects the project. Setup
|
|
229
|
+
connects the client to the single running server and does not accept `--project`.
|
|
234
230
|
|
|
235
|
-
|
|
236
|
-
`softpractice` server in the MCP settings. Ask the agent: “Use the
|
|
237
|
-
SoftPractice MCP server to show my lesson status and current task.” It
|
|
238
|
-
should call `status` and `task`. When switching to another lesson project,
|
|
239
|
-
run the command again in its folder or pass
|
|
240
|
-
`--project /absolute/path/to/your/lesson-project`.
|
|
231
|
+
### Checking the server
|
|
241
232
|
|
|
242
|
-
|
|
233
|
+
From any folder, check which server is running:
|
|
243
234
|
|
|
244
235
|
```bash
|
|
245
|
-
softpractice mcp
|
|
236
|
+
softpractice mcp status
|
|
237
|
+
softpractice mcp status --json
|
|
246
238
|
```
|
|
247
239
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
[official Codex MCP documentation](https://developers.openai.com/codex/mcp).
|
|
240
|
+
The command checks a live connection and shows the lesson folder, PID,
|
|
241
|
+
local address, and CLI version. A stopped server returns `not_running`;
|
|
242
|
+
a key file left after a crash is not treated as proof of a running server.
|
|
243
|
+
No lesson project or sign-in is needed. This reports the local process;
|
|
244
|
+
lesson information remains available through `softpractice status` and the
|
|
245
|
+
MCP `status` tool.
|
|
255
246
|
|
|
256
|
-
###
|
|
247
|
+
### Stopping the server and removing the connection
|
|
257
248
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
active servers.
|
|
249
|
+
Press Ctrl+C in the server's terminal to stop the lesson server. The client
|
|
250
|
+
configuration remains available for the next startup.
|
|
261
251
|
|
|
262
|
-
To
|
|
252
|
+
To remove the client connection, run from any folder:
|
|
263
253
|
|
|
264
254
|
```bash
|
|
265
|
-
|
|
266
|
-
|
|
255
|
+
softpractice mcp remove claude-desktop
|
|
256
|
+
# or
|
|
257
|
+
softpractice mcp remove codex-desktop
|
|
267
258
|
```
|
|
268
259
|
|
|
269
|
-
|
|
270
|
-
the
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
260
|
+
This removes only the SoftPractice entry, preserves other settings, and saves
|
|
261
|
+
the previous file as `.bak`. Repeating the command is safe: missing entries
|
|
262
|
+
or files are left untouched. Restart the client to apply the change. Codex
|
|
263
|
+
shares these settings between Desktop, CLI, and the IDE extension; project
|
|
264
|
+
settings may override them.
|
|
265
|
+
|
|
266
|
+
Removing the connection does not stop the lesson server. To reconnect,
|
|
267
|
+
run the corresponding `softpractice mcp setup` command again.
|
|
274
268
|
|
|
275
269
|
### Using the server
|
|
276
270
|
|
package/package.json
CHANGED