@softpractice/softpractice-cli 0.2.1 → 0.2.3
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 +93 -83
- 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,136 @@ 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
|
-
|
|
158
|
+
Install the CLI (see [Install](#install)), then configure your desktop client.
|
|
159
|
+
For Claude Desktop, install and open the app once before setup.
|
|
160
|
+
You do not need a lesson project yet:
|
|
161
161
|
|
|
162
162
|
```bash
|
|
163
|
-
softpractice
|
|
164
|
-
|
|
165
|
-
softpractice
|
|
163
|
+
softpractice mcp setup claude-desktop
|
|
164
|
+
# or
|
|
165
|
+
softpractice mcp setup codex-desktop
|
|
166
166
|
```
|
|
167
167
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
`softpractice mcp` in your client. The client starts it for you, so you do not
|
|
171
|
-
need to leave it running in a terminal.
|
|
168
|
+
After setup, quit the desktop client completely and start it again to load
|
|
169
|
+
the connection settings.
|
|
172
170
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
171
|
+
Setup registers the CLI's absolute executable path and `mcp connect` as the
|
|
172
|
+
launch arguments. It only updates the configuration; it does not start a
|
|
173
|
+
server or install a service that runs when the computer starts. It preserves
|
|
174
|
+
other settings and saves the previous file as `.bak`. Claude Desktop uses
|
|
175
|
+
`claude_desktop_config.json`; on Windows, setup also finds the configuration used by the Microsoft Store version. Codex uses
|
|
176
|
+
`~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and a tool timeout of
|
|
177
|
+
180 seconds. Codex Desktop, CLI, and the IDE extension share these settings.
|
|
178
|
+
No separate Codex CLI installation is needed for desktop setup.
|
|
178
179
|
|
|
179
|
-
|
|
180
|
+
For manual configuration, append `--print` to either setup command. It prints
|
|
181
|
+
the JSON or TOML entry without writing settings. Replace an existing
|
|
182
|
+
`softpractice` entry rather than adding a duplicate.
|
|
180
183
|
|
|
181
|
-
|
|
184
|
+
### Start the lesson server
|
|
185
|
+
|
|
186
|
+
Sign in, then start the server for a Git project downloaded with
|
|
187
|
+
`softpractice starter` or restored with `softpractice project restore`:
|
|
182
188
|
|
|
183
189
|
```bash
|
|
184
|
-
softpractice
|
|
190
|
+
softpractice login
|
|
191
|
+
cd /path/to/your/lesson-project
|
|
192
|
+
softpractice mcp
|
|
185
193
|
```
|
|
186
194
|
|
|
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:
|
|
195
|
+
Or start from any folder with an explicit project:
|
|
202
196
|
|
|
203
197
|
```bash
|
|
204
|
-
softpractice mcp
|
|
198
|
+
softpractice mcp --project /path/to/your/lesson-project
|
|
205
199
|
```
|
|
206
200
|
|
|
207
|
-
|
|
201
|
+
Keep this terminal open. The server validates the Git repository and
|
|
202
|
+
SoftPractice project link before accepting connections. It uses the CLI's
|
|
203
|
+
saved sign-in; it never opens a sign-in flow itself.
|
|
208
204
|
|
|
209
|
-
|
|
205
|
+
On macOS, Linux, and Windows, the client automatically starts
|
|
206
|
+
`softpractice mcp connect` and communicates with it over stdio. This connection
|
|
207
|
+
process is separate from the lesson server started in your terminal. It stays
|
|
208
|
+
connected even when no lesson server is running. You can open
|
|
209
|
+
Claude Desktop or Codex Desktop before starting the lesson: tools remain
|
|
210
|
+
listed, and a lesson request explains how to start the server. Start, stop,
|
|
211
|
+
or restart the lesson server without restarting Desktop, then repeat the
|
|
212
|
+
request. Pending confirmations become invalid if the lesson server restarts.
|
|
213
|
+
No system service is installed; the client owns the connection process.
|
|
210
214
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
+
The lesson server listens on `127.0.0.1:39473`. Connections require a random
|
|
216
|
+
per-run key saved in the CLI's user configuration folder. Both processes
|
|
217
|
+
must run on the same computer under the same user and use the same
|
|
218
|
+
`SOFTPRACTICE_CONFIG_DIR` if that environment variable is set. This address
|
|
219
|
+
is not an HTTP URL.
|
|
215
220
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
221
|
+
Only one lesson server can run on this computer at a time. To switch projects,
|
|
222
|
+
stop it with Ctrl+C and start it in the other lesson folder. The next request
|
|
223
|
+
uses the new project. Setup does not need to be repeated.
|
|
219
224
|
|
|
220
|
-
### Codex
|
|
225
|
+
### Claude Code and Codex CLI
|
|
221
226
|
|
|
222
|
-
|
|
227
|
+
To use the same manually started server:
|
|
223
228
|
|
|
224
229
|
```bash
|
|
225
|
-
softpractice mcp
|
|
230
|
+
claude mcp add --transport stdio --scope user softpractice -- softpractice mcp connect
|
|
231
|
+
# or, if Codex Desktop setup has not already configured it:
|
|
232
|
+
codex mcp add softpractice -- softpractice mcp connect
|
|
226
233
|
```
|
|
227
234
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
and
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
235
|
+
If the client cannot find `softpractice`, use the executable's full path.
|
|
236
|
+
See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp)
|
|
237
|
+
and [Codex MCP documentation](https://developers.openai.com/codex/mcp).
|
|
238
|
+
|
|
239
|
+
`softpractice mcp` always starts the local server, including with redirected
|
|
240
|
+
stdin or in the background. Only server startup selects the project. Setup
|
|
241
|
+
registers the connection command and does not accept `--project`.
|
|
242
|
+
The lesson server must be running for tools to work with the lesson.
|
|
234
243
|
|
|
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`.
|
|
244
|
+
### Checking the server
|
|
241
245
|
|
|
242
|
-
|
|
246
|
+
From any folder, check which server is running:
|
|
243
247
|
|
|
244
248
|
```bash
|
|
245
|
-
softpractice mcp
|
|
249
|
+
softpractice mcp status
|
|
250
|
+
softpractice mcp status --json
|
|
246
251
|
```
|
|
247
252
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
253
|
+
The command checks a live connection and shows the lesson folder, PID,
|
|
254
|
+
local address, and CLI version. A stopped server returns `not_running`;
|
|
255
|
+
a key file left after a crash is not treated as proof of a running server.
|
|
256
|
+
No lesson project or sign-in is needed. This reports the lesson server,
|
|
257
|
+
not the client connection process. Lesson information is available through
|
|
258
|
+
`softpractice status` and, while the lesson server is running, the MCP
|
|
259
|
+
`status` tool.
|
|
255
260
|
|
|
256
|
-
###
|
|
261
|
+
### Stopping the server and removing the connection
|
|
257
262
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
263
|
+
Press Ctrl+C in the server's terminal to stop the lesson server. The MCP
|
|
264
|
+
connection remains active, but lesson requests ask you to start the lesson
|
|
265
|
+
server. Start it again and repeat the request; no client restart is
|
|
266
|
+
needed.
|
|
261
267
|
|
|
262
|
-
To
|
|
268
|
+
To remove the client connection, run from any folder:
|
|
263
269
|
|
|
264
270
|
```bash
|
|
265
|
-
|
|
266
|
-
|
|
271
|
+
softpractice mcp remove claude-desktop
|
|
272
|
+
# or
|
|
273
|
+
softpractice mcp remove codex-desktop
|
|
267
274
|
```
|
|
268
275
|
|
|
269
|
-
|
|
270
|
-
the
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
276
|
+
This removes only the SoftPractice entry, preserves other settings, and saves
|
|
277
|
+
the previous file as `.bak`. Repeating the command is safe: missing entries
|
|
278
|
+
or files are left untouched. Restart the client to apply the change. Codex
|
|
279
|
+
shares these settings between Desktop, CLI, and the IDE extension; project
|
|
280
|
+
settings may override them.
|
|
281
|
+
|
|
282
|
+
Removing the connection does not stop the lesson server. To reconnect,
|
|
283
|
+
run the corresponding `softpractice mcp setup` command again.
|
|
274
284
|
|
|
275
285
|
### Using the server
|
|
276
286
|
|
package/package.json
CHANGED