Skip to content

Commit dd0d053

Browse files
cliffhallclaude
andcommitted
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]>
1 parent acd1f2e commit dd0d053

1 file changed

Lines changed: 11 additions & 9 deletions

File tree

  • .claude/skills/project-structure

‎.claude/skills/project-structure/SKILL.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@ includes the tests) and `vitest.config.ts`.
2929
| Server | Layout | Where its features are registered |
3030
| --- | --- | --- |
3131
| `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()` |
3535

3636
Three things about `everything` that the table cannot hold:
3737

@@ -50,11 +50,13 @@ Three things about `everything` that the table cannot hold:
5050
`structure.md`, and `src/everything/AGENTS.md` holds the rules that apply
5151
only inside that directory.
5252

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.
5860

5961
## The Python servers
6062

@@ -88,7 +90,7 @@ importable.
8890
| --- | --- |
8991
| 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` |
9092
| 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) |
9294
| 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 |
9395
| A helper module for `filesystem`, `memory` or `sequentialthinking` | A kebab-case `.ts` file at the workspace root, imported with the `.js` extension |
9496
| 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

Comments
 (0)