Skip to content

Commit 39976a4

Browse files
olaservoolaservo
authored
Merge pull request #945 from olaservo/v2/feature/tech-stack-votes
V2 Spec Additions
2 parents 59b5928 + a13a05d commit 39976a4

File tree

5 files changed

+1506
-5
lines changed

5 files changed

+1506
-5
lines changed

‎specification/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Inspector V2 Brief
22

3-
### Brief | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
3+
### Brief | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md) | [V2 UX](v2_ux.md)
44

55
## Table of Contents
66
* [Motivation and Context](#motivation-and-context)

‎specification/v1_problems.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Inspector V1 Problems
22

3-
### [Brief](README.md) | V1 Problems | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
3+
### [Brief](README.md) | V1 Problems | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md) | [V2 UX](v2_ux.md)
44

55
## Table of Contents
66
* [Monolithic components](#monolithic-components)

‎specification/v2_scope.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Inspector V2 Scope
22

3-
### [Brief](README.md) | [V1 Problems](v1_problems.md) | V2 Scope | [V2 Tech Stack](v2_tech_stack.md)
3+
### [Brief](README.md) | [V1 Problems](v1_problems.md) | V2 Scope | [V2 Tech Stack](v2_tech_stack.md) | [V2 UX](v2_ux.md)
44

55
## Table of Contents
66
* [Protocol Features](#protocol-features)

‎specification/v2_tech_stack.md‎

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Inspector V2 Tech Stack
22

3-
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | V2 Tech Stack
3+
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | V2 Tech Stack | [V2 UX](v2_ux.md)
44

55
## Table of Contents
66
* [Web Client](#web-client)
@@ -29,13 +29,101 @@ Let's choose a feature-rich component set with easy theming control
2929

3030
### Transport Operation
3131
Let's consider how to operate the server transports.
32+
* -[x] [Hono](https://hono.dev/)
3233
* -[ ] [Express](https://expressjs.com/)
3334
* -[ ] Node:[http](https://nodejs.org/docs/v22.18.0/api/http.html)
3435

36+
#### Hono Rationale
37+
38+
Hono is selected based on community consensus (PR #945 discussion) for alignment with modern web standards and the TypeScript SDK v2 direction.
39+
40+
**Why Hono over Express:**
41+
42+
| Requirement | Hono | Express |
43+
|-------------|------|---------|
44+
| Bundle size | 12kb | ~1mb |
45+
| Web Standards (Request/Response) | Yes - Native | No - Shimmed |
46+
| TypeScript native | Yes | No - @types package |
47+
| Tree-shakable | Yes - Fully | No |
48+
| HTTP/2 support | Yes | No (SPDY dropped) |
49+
| Built-in middleware | Yes - Body parsing, auth, etc. | No - Requires plugins |
50+
| Edge/serverless deployment | Yes - Native | Partial - Requires adapters |
51+
52+
**Benefits:**
53+
54+
1. **Web Standards Alignment** - Uses native `Request`/`Response` objects, enabling deployment across Node, Deno, Bun, serverless, and edge environments
55+
2. **TypeScript Native** - Full type safety without external type packages, no monkey-patching of request objects
56+
3. **Future-proofing** - HTTP/2 support enables potential gRPC transport; aligns with TypeScript SDK v2 plans
57+
4. **Developer Experience** - Simpler API, type-safe context, smaller learning curve
58+
5. **Bundle Efficiency** - Dramatically smaller footprint benefits both development and deployment
59+
3560
### Logging
3661
Let's step up our logging capability with an advanced logger:
3762
* -[ ] [Winston](https://github.com/winstonjs/winston?tab=readme-ov-file#winston)
38-
* -[ ] [Pino](https://github.com/pinojs/pino?tab=readme-ov-file#pino)
63+
* -[x] [Pino](https://github.com/pinojs/pino?tab=readme-ov-file#pino)
3964
* -[ ] [Morgan](https://github.com/expressjs/morgan?tab=readme-ov-file#morgan)
4065
* -[ ] [Log4js](https://github.com/stritti/log4js?tab=readme-ov-file#log4js)
4166
* -[ ] [Bunyan](https://github.com/trentm/node-bunyan)
67+
68+
#### Pino Rationale
69+
70+
Pino is selected for synergy with the **History Screen** feature. The log file serves dual purposes:
71+
1. **Server diagnostics** - Standard application logging
72+
2. **History persistence** - Request/response replay source
73+
74+
**Why Pino over Winston:**
75+
76+
| Requirement | Pino | Winston |
77+
|-------------|------|---------|
78+
| Default JSON format | Yes - NDJSON | No - Text (needs config) |
79+
| Line-by-line parsing | Yes - Native | No - Extra work |
80+
| High-throughput logging | Yes - Very fast | Partial - Slower |
81+
| Log rotation | Yes - pino-roll | Yes - winston-daily-rotate |
82+
| Dev-friendly output | Yes - pino-pretty | Yes - Built-in |
83+
84+
**Architecture:**
85+
86+
```
87+
┌─────────────────────────────────────────────────────────────────┐
88+
│ Proxy Server │
89+
│ │
90+
│ MCP Request ──▶ Pino Logger ──┬──▶ history.ndjson (file) │
91+
│ │ │
92+
│ └──▶ Console (pino-pretty) │
93+
│ │
94+
│ History API: GET /api/history?method=tools/call&limit=50 │
95+
│ (parses history.ndjson, returns filtered JSON) │
96+
└─────────────────────────────────────────────────────────────────┘
97+
```
98+
99+
**Log Entry Schema:**
100+
101+
Each MCP operation logs a request/response pair:
102+
103+
```json
104+
{"ts":1732987200000,"level":"info","type":"mcp_request","method":"tools/call","target":"echo","params":{"message":"hello"},"requestId":"abc123","serverId":"my-server"}
105+
{"ts":1732987200045,"level":"info","type":"mcp_response","requestId":"abc123","result":{"content":[{"type":"text","text":"hello"}]},"duration":45,"success":true}
106+
```
107+
108+
**Schema fields:**
109+
110+
| Field | Description |
111+
|-------|-------------|
112+
| `ts` | Unix timestamp (ms) |
113+
| `level` | Log level (info, error) |
114+
| `type` | `mcp_request` or `mcp_response` |
115+
| `method` | MCP method (tools/call, resources/read, prompts/get, etc.) |
116+
| `target` | Tool name, resource URI, or prompt name |
117+
| `params` | Request parameters |
118+
| `requestId` | Correlation ID linking request to response |
119+
| `serverId` | Server identifier |
120+
| `result` | Response data (for mcp_response) |
121+
| `error` | Error message (for failed requests) |
122+
| `duration` | Response time in ms |
123+
| `success` | Boolean success indicator |
124+
125+
**Dependencies:**
126+
- `pino` - Core logger
127+
- `pino-pretty` - Dev console formatting
128+
- `pino-roll` - Log rotation (optional)
129+
- `pino-http` - Express integration

0 commit comments

Comments
 (0)