You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0223d22
Browse filesBrowse the repository at this point in the historyBrowse files
docs(project-structure): describe the createServer() factories the server PRs add
The four per-server PRs of #4854 (#4970, #4973, #4977, #4978) give every
TypeScript server a createServer() factory and an entry-point guard, and
move filesystem's registrations into server.ts. Update the layout table,
the "where a new tool goes" row, and replace the "run on import" paragraph,
which those PRs make false. Like the rest of this PR, this describes the
repo after they merge.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: cliffhall <[email protected]>
Copy file name to clipboardExpand all lines: .claude/skills/project-structure/SKILL.md
+11-9Lines changed: 11 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,9 +29,9 @@ includes the tests) and `vitest.config.ts`.
29
29
| Server | Layout | Where its features are registered |
30
30
| --- | --- | --- |
31
31
|`everything`|`index.ts` picks a transport from `argv`; `server/` holds the factory; `tools/`, `resources/`, `prompts/` hold one file per feature plus an `index.ts`; `transports/` holds one file per transport; `version.ts` reads the package version; `docs/` is shipped | Each feature file exports a `register…` function, wired into its area's `index.ts` (`registerTools`, `registerResources`, `registerPrompts`), which `server/index.ts` calls from `createServer()`|
32
-
|`filesystem`|`index.ts` is the server; `lib.ts` holds the file operations and path validation; `path-utils.ts`, `path-validation.ts` and `roots-utils.ts` are focused helpers; `version.ts` reads the package version | Inline in `index.ts`, with `server.registerTool(...)`|
33
-
|`memory`|`index.ts`is the server and the `KnowledgeGraphManager`; `version.ts` reads the package version | Inline in `index.ts`; the resource and its subscription handlers are exported `register…` functions in the same file |
34
-
|`sequentialthinking`|`index.ts`is the server; `lib.ts` holds `SequentialThinkingServer`, the logic; `version.ts` reads the package version | Inline in `index.ts`|
32
+
|`filesystem`|`index.ts` is the stdio entry point (argv → allowed directories, `main()`); `server.ts` exports `createServer(allowedDirectories)`; `lib.ts` holds the file operations and path validation, with the allow-list passed in rather than held globally; `path-utils.ts`, `path-validation.ts` and `roots-utils.ts` are focused helpers; `version.ts` reads the package version | Inline in `createServer()` in `server.ts`, with `server.registerTool(...)`|
33
+
|`memory`|`index.ts`holds the `KnowledgeGraphManager`, `createServer(memoryFilePath)`and the stdio `main()`; `version.ts` reads the package version | Inline in `createServer()`; the resource and its subscription handlers are exported `register…` functions in the same file |
34
+
|`sequentialthinking`|`index.ts`holds `createServer()` and the stdio `main()`; `lib.ts` holds `SequentialThinkingServer`, the logic; `version.ts` reads the package version | Inline in `createServer()`|
35
35
36
36
Three things about `everything` that the table cannot hold:
37
37
@@ -50,11 +50,13 @@ Three things about `everything` that the table cannot hold:
50
50
`structure.md`, and `src/everything/AGENTS.md` holds the rules that apply
51
51
only inside that directory.
52
52
53
-
`filesystem`, `memory` and `sequentialthinking` run on import: each `index.ts`
54
-
builds the server at module scope and connects stdio at the bottom of the
55
-
file. That is why their logic lives in a separate module (`lib.ts`) or is
56
-
exported from `index.ts` for the tests, and why a test cannot import a ready
57
-
server from them. `/testing` covers what that means for a new test.
53
+
**No server starts on import.** Each one builds its server in a
54
+
`createServer(...)` factory, and its entry file connects a transport only when
55
+
it is the process entry point (an `isEntryPoint()` or `isMainModule()` check
56
+
that compares real paths, so the npm bin symlink still starts it). Keep it that
57
+
way: a module that binds a port, connects stdio or installs a signal handler at
58
+
import cannot be driven in-process by the tests. `/testing` covers the
59
+
in-process harness.
58
60
59
61
## The Python servers
60
62
@@ -88,7 +90,7 @@ importable.
88
90
| --- | --- |
89
91
| A tool, resource or prompt for `everything`| Its own kebab-case file in `tools/`, `resources/` or `prompts/`, exporting a `register…` function, wired into that directory's `index.ts`|
90
92
| A transport for `everything`|`src/everything/transports/`, plus a `case` in `src/everything/index.ts` and a `start:…` script |
91
-
| A tool for `filesystem`, `memory` or `sequentialthinking`| A `server.registerTool(...)` call in that server's `index.ts`; the logic it calls goes in `lib.ts` (or the class it extends) so a test can reach it|
93
+
| A tool for `filesystem`, `memory` or `sequentialthinking`| A `server.registerTool(...)` call inside that server's `createServer()` (`server.ts` in `filesystem`, `index.ts` in the other two); the logic it calls goes in `lib.ts` (or the class it extends) |
92
94
| A helper module for `everything`| A kebab-case `.ts` file in the feature area it supports, beside its users (`server/logging.ts`, `server/roots.ts`, `resources/session.ts`), imported with the `.js` extension |
93
95
| A helper module for `filesystem`, `memory` or `sequentialthinking`| A kebab-case `.ts` file at the workspace root, imported with the `.js` extension |
94
96
| A tool for a Python server |`server.py`: the tool-name enum member (`git`, `time`), the model, the `list_tools` entry, the `call_tool` branch |
0 commit comments