@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.
Files changed (2) hide show
  1. package/README.md +78 -84
  2. 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. It is a local **stdio** MCP server: your MCP client
153
- starts the process and communicates with it. No server URL or listening port
154
- is needed.
154
+ reading the evaluation.
155
155
 
156
- ### Before connecting
156
+ ### Configure once, from any folder
157
157
 
158
- Install the CLI (see [Install](#install)), sign in, and open an existing lesson
159
- Git project, downloaded with `softpractice starter` or restored with
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 login
164
- cd /path/to/your/lesson-project
165
- softpractice status
162
+ softpractice mcp setup claude-desktop
163
+ # or
164
+ softpractice mcp setup codex-desktop
166
165
  ```
167
166
 
168
- The MCP server uses the CLI's saved sign-in. It never starts a sign-in itself;
169
- there is no separate MCP OAuth login. Configure the launch command
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.
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
- By default it works in the directory where the client starts it. Use
174
- `--project /absolute/path/to/your/lesson-project` to pin the folder, especially
175
- for desktop clients. When switching projects, change that path. If the client
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
- ### Claude Desktop
179
+ ### Start the lesson server
180
180
 
181
- From the lesson project folder:
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 mcp setup claude-desktop
185
+ softpractice login
186
+ cd /path/to/your/lesson-project
187
+ softpractice mcp
185
188
  ```
186
189
 
187
- The command adds the `softpractice` server to the Claude Desktop settings
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 setup claude-desktop --print
193
+ softpractice mcp --project /path/to/your/lesson-project
205
194
  ```
206
195
 
207
- ### Claude Code
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
- From the lesson project folder:
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
- ```bash
212
- claude mcp add --transport stdio --scope local softpractice -- softpractice mcp
213
- claude mcp list
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
- This registration is private to you and applies to this project. Start Claude
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
- ### Codex Desktop
221
-
222
- From the lesson project folder:
215
+ To use the same manually started server:
223
216
 
224
217
  ```bash
225
- softpractice mcp setup codex-desktop
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
- You do not need to install Codex CLI. The command adds the `softpractice`
229
- server to `~/.codex/config.toml` with absolute paths to the program and project
230
- and a tool timeout of 180 seconds. If `CODEX_HOME` is set, it uses
231
- `config.toml` in that folder. Other settings, servers, and their comments
232
- are kept; the previous file is saved next to it as `config.toml.bak`.
233
- Running setup again for the same project leaves the file unchanged.
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
- Restart Codex Desktop, open the lesson project folder, and check the
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
- To configure the app manually, print the TOML entry:
233
+ From any folder, check which server is running:
243
234
 
244
235
  ```bash
245
- softpractice mcp setup codex-desktop --print
236
+ softpractice mcp status
237
+ softpractice mcp status --json
246
238
  ```
247
239
 
248
- Add it to `config.toml`, keeping the servers already configured. If
249
- `[mcp_servers.softpractice]` already exists, replace that table instead of
250
- adding a duplicate. Codex Desktop, CLI, and the IDE extension share these
251
- settings on the same host. Setup pins one project to the `softpractice`
252
- server for all these clients. A trusted project's `.codex/config.toml` can
253
- override user-level settings. See the
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
- ### Codex CLI
247
+ ### Stopping the server and removing the connection
257
248
 
258
- If you already configured Codex Desktop with the command above, no further
259
- registration is needed. Start `codex` in the lesson folder; `/mcp` shows
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 configure using Codex CLI, replace the project path:
252
+ To remove the client connection, run from any folder:
263
253
 
264
254
  ```bash
265
- codex mcp add softpractice -- softpractice mcp --project /path/to/your/lesson-project
266
- codex mcp list
255
+ softpractice mcp remove claude-desktop
256
+ # or
257
+ softpractice mcp remove codex-desktop
267
258
  ```
268
259
 
269
- For local checks and evaluation polling, add `tool_timeout_sec = 180` to
270
- the generated `[mcp_servers.softpractice]` table in `~/.codex/config.toml`.
271
- If the client cannot find `softpractice`, use the executable's full path.
272
- You can also use `softpractice mcp setup codex-desktop`: it configures the
273
- same file.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softpractice/softpractice-cli",
3
- "version": "0.2.1",
3
+ "version": "0.2.2",
4
4
  "description": "CLI for SoftPractice, an online platform for project-based programming practice",
5
5
  "license": "MIT",
6
6
  "author": "Arthur Sultanbekov",