@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.
Files changed (2) hide show
  1. package/README.md +93 -83
  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,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. 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
+ 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 login
164
- cd /path/to/your/lesson-project
165
- softpractice status
163
+ softpractice mcp setup claude-desktop
164
+ # or
165
+ softpractice mcp setup codex-desktop
166
166
  ```
167
167
 
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.
168
+ After setup, quit the desktop client completely and start it again to load
169
+ the connection settings.
172
170
 
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.
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
- ### Claude Desktop
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
- From the lesson project folder:
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 mcp setup claude-desktop
190
+ softpractice login
191
+ cd /path/to/your/lesson-project
192
+ softpractice mcp
185
193
  ```
186
194
 
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:
195
+ Or start from any folder with an explicit project:
202
196
 
203
197
  ```bash
204
- softpractice mcp setup claude-desktop --print
198
+ softpractice mcp --project /path/to/your/lesson-project
205
199
  ```
206
200
 
207
- ### Claude Code
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
- From the lesson project folder:
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
- ```bash
212
- claude mcp add --transport stdio --scope local softpractice -- softpractice mcp
213
- claude mcp list
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
- 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).
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 Desktop
225
+ ### Claude Code and Codex CLI
221
226
 
222
- From the lesson project folder:
227
+ To use the same manually started server:
223
228
 
224
229
  ```bash
225
- softpractice mcp setup codex-desktop
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
- 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.
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
- 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`.
244
+ ### Checking the server
241
245
 
242
- To configure the app manually, print the TOML entry:
246
+ From any folder, check which server is running:
243
247
 
244
248
  ```bash
245
- softpractice mcp setup codex-desktop --print
249
+ softpractice mcp status
250
+ softpractice mcp status --json
246
251
  ```
247
252
 
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).
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
- ### Codex CLI
261
+ ### Stopping the server and removing the connection
257
262
 
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.
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 configure using Codex CLI, replace the project path:
268
+ To remove the client connection, run from any folder:
263
269
 
264
270
  ```bash
265
- codex mcp add softpractice -- softpractice mcp --project /path/to/your/lesson-project
266
- codex mcp list
271
+ softpractice mcp remove claude-desktop
272
+ # or
273
+ softpractice mcp remove codex-desktop
267
274
  ```
268
275
 
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.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@softpractice/softpractice-cli",
3
- "version": "0.2.1",
3
+ "version": "0.2.3",
4
4
  "description": "CLI for SoftPractice, an online platform for project-based programming practice",
5
5
  "license": "MIT",
6
6
  "author": "Arthur Sultanbekov",