Skip to content

Commit fb88a0c

Browse files
cliffhallcliffhall
committed
Initial contents
* Basic .gitignore * specification folder with * README.md * v1_problems.md * v2_scope.md * v2_tech_stack.md
1 parent d5fef7e commit fb88a0c

File tree

4 files changed

+245
-0
lines changed

4 files changed

+245
-0
lines changed

‎specification/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Inspector V2 Brief
2+
3+
### Brief | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
4+
5+
## Table of Contents
6+
* [Motivation and Context](#motivation-and-context)
7+
* [Track Protocol Conformance](#track-protocol-conformance)
8+
* [Improve Maintainability](#improve-maintainability)
9+
* [Provide Extensibility](#provide-extensibility)
10+
* [Proper Documentation](#proper-documentation)
11+
12+
## Motivation and Context
13+
14+
The existing Inspector is hard to maintain for a number of reasons. We decided to create a more maintainable Inspector
15+
from the ground up, that retains the deterministic boundary of operation, but exposes a plugin architecture.
16+
17+
## Track Protocol Conformance
18+
* Identify any gaps in V1 inspector
19+
* Track which features are covered
20+
* Implement to parity and fill gaps
21+
* Provide conformance testing in CI
22+
23+
## Improve Maintainability
24+
* Clearer separation of concerns
25+
* Smaller, reusable components
26+
27+
## Provide Extensibility
28+
* Plugin SDK / API
29+
* Third parties cand develop/maintain their own plugins for features such as
30+
* LLM usage
31+
* Evals
32+
* Multiple server connections
33+
* Apps playground
34+
* Testing of registry configuration
35+
* Interface with registry
36+
37+
## Proper Documentation
38+
* One big README won't cut it anymore
39+
* Published documentation in MDX should
40+
* Render in style of spec
41+
* Kept up to date
42+
* Cover all features
43+
* Discuss troubleshooting strategies
44+
* Provide detailed contribution guidance that explains architecture and expected idioms
45+

‎specification/v1_problems.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Inspector V1 Problems
2+
3+
### [Brief](README.md) | V1 Problems | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
4+
5+
## Table of Contents
6+
* [Monolithic components](#monolithic-components)
7+
* [Monolithic hooks](#monolithic-hooks)
8+
* [Environment variable explosion](#environment-variable-explosion-)
9+
* [Disparate OAuth flows](#disparate-oauth-flows-)
10+
* [CLI version combined with UI version](#cli-version-combined-with-ui-version-)
11+
12+
## Monolithic components
13+
* Hard to read and maintain
14+
* Deeply custom:
15+
* Divs all the way down,
16+
* Strewn with hundreds of css classes
17+
### Solution
18+
* Make a kit of small, reusable components that are already styled for use anywhere in the app
19+
* Easier to reason about than inline-customized primitives
20+
* Minimize css for inline customization
21+
* Only pass state
22+
* Define functions to use as handlers rather than writing inline in code
23+
* Makes component instantiation markup smaller and easier to understand
24+
* Separates code from markup
25+
26+
## Monolithic hooks
27+
* E.g., `useConnection` is nearly 1k lines long
28+
29+
### Solution
30+
* Extract inline logic out to function libraries / classes that are easier to reason about and test in isolation
31+
32+
## Environment variable explosion
33+
* We have a configuration file but it is for servers, not things like request timeouts, etc
34+
* The addition of a new environment variable for everything someone wants to configure is problematic.
35+
* It’s easy to misspell the variable name and the names
36+
* Often not named in the best way
37+
* Lots of touch points to update for a new variable
38+
39+
### Solution
40+
* A JSON configuration file would be a better approach.
41+
* Hierarchical groups of settings could be used
42+
* Different files for different configurations
43+
* Expanding the format to include other settings
44+
* A configuration file could be validated, so misspelled keys would be caught at startup
45+
46+
## Disparate OAuth flows
47+
* We often have deviations of behavior between basic flow, quick flow, and guided flow
48+
* Each flow has independent code paths that can break or behave differently from the others
49+
50+
### Solution
51+
* Use a single auth flow mechanism that operates in all three states while supporting different configurations
52+
53+
## CLI version combined with UI version
54+
* Both projects are not kept in parity and do not share significant overlap as to belong in the same repo
55+
56+
### Solution
57+
* Refactor/extract the CLI Inspector to a separate repo for ongoing development
58+
59+

‎specification/v2_scope.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Inspector V2 Scope
2+
3+
### [Brief](README.md) | [V1 Problems](v1_problems.md) | V2 Scope | [V2 Tech Stack](v2_tech_stack.md)
4+
5+
## Table of Contents
6+
* [Protocol Features](#protocol-features)
7+
* [OAuth Handling](#oauth-handling)
8+
* [Transport Types](#transport-types)
9+
* [Connection Type](#connection-type)
10+
* [Logging Level Control](#logging-level-control)
11+
* [Copy Server configuration](#copy-server-configuration)
12+
* [Custom Auth-related properties](#custom-auth-related-properties)
13+
* [Timeout management](#timeout-management)
14+
* [Schema parsing for Elicitation, Tool Input Schemas](#schema-parsing-for-elicitation-tool-input-schemas)
15+
* [Form inputs vs JSON editor for:](#form-inputs-vs-json-editor-for)
16+
* [Proxy server](#proxy-server)
17+
* [Previous Security Fixes](#previous-security-fixes)
18+
* [Server file maintenance](#server-file-maintenance)
19+
* [Plugin architecture](#plugin-architecture)
20+
21+
## Protocol Features
22+
* Tools
23+
* Resources
24+
* Resource Subscriptions
25+
* Resource Templates
26+
* Prompts
27+
* Elicitation
28+
* Sampling with stubbed response
29+
* Roots
30+
* Logging
31+
* Completions
32+
* Metadata
33+
* Pagination
34+
* resources/list
35+
* resources/templates/list
36+
* prompts/list
37+
* tools/list
38+
* Cancellation (of in progress requests)
39+
* Ping
40+
41+
## OAuth Handling
42+
* Quick Flow
43+
* Guided Flow
44+
* Basic (non debugger) Flow
45+
46+
## Transport Types
47+
* STDIO
48+
* SSE
49+
* SHTTP
50+
51+
## Connection Type
52+
* Direct
53+
* Via Proxy
54+
55+
## Logging Level Control
56+
* Present and synchronized when connecting to server with logging capability
57+
58+
## Copy Server configuration
59+
* As config file server entry
60+
* As config file containing server entry
61+
62+
## Custom Auth-related properties
63+
* Custom headers
64+
* Client ID
65+
* Secret
66+
* Scope
67+
68+
## Timeout management
69+
* Request timeout
70+
* Request timeout on progress (bool)
71+
* Maximum total timeout
72+
73+
## Schema parsing for Elicitation, Tool Input Schemas
74+
* New enum types
75+
* anyOf /oneOf
76+
* $ref
77+
* $defs
78+
79+
## Form inputs vs JSON editor for:
80+
* Elicitation, tool input, resource template, and prompt vars, sampling response
81+
* Field types of primitive, object, array
82+
* Nullable field types
83+
* Defaults
84+
85+
## Proxy server
86+
* Required for testing STDIO servers and HTTP servers that can’t open up their CORS origin for testing
87+
* Implement a feature configuration file rather than disparate environment variables for everything
88+
* Handle auth flows instead of browser when "via proxy" connection type selected
89+
90+
## Previous Security Fixes
91+
* Unique proxy server session token to prevent unauthorized access to the proxy server's ability to execute local processes and connect to MCP servers.
92+
* Bind to localhost by default to prevent DNS rebinding attacks (never 0.0.0.0)
93+
* Fix/validate redirect urls for http/https scheme only in auth flow
94+
95+
## Server file maintenance
96+
* Opening screen similar to MCPJam servers list
97+
* Adding, changing, and deleting a server would hit endpoints on the proxy server update the inspector’s servers.json config file
98+
99+
## Plugin architecture
100+
* Allow third parties to extend the Inspector with functionality we do not wish to maintain, but which would still be useful to developers within the context of the Inspector, e.g., LLMs, evals, OpenAI Apps SDK playground

‎specification/v2_tech_stack.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Inspector V2 Tech Stack
2+
3+
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | V2 Tech Stack
4+
5+
## Table of Contents
6+
* [Web Client](#web-client)
7+
* [Language and Framework](#language-and-framework)
8+
* [Components and theme](#components-and-theme)
9+
* [Proxy Server](#proxy-server)
10+
* [Language and Runtime](#language-and-runtime)
11+
* [Transport Operation](#server)
12+
* [Logging](#logging)
13+
14+
15+
## Web Client
16+
### Language and Framework
17+
* Typescript
18+
* React
19+
20+
### Components and Theme
21+
Let's choose a feature-rich component set with easy theming control
22+
* -[ ] [Mantine](https://ui.mantine.dev/)
23+
* -[ ] [Shadcdn](https://ui.shadcn.com/)
24+
25+
## Proxy Server
26+
### Language and Runtime
27+
* Typescript
28+
* Node
29+
30+
### Transport Operation
31+
Let's consider how to operate the server transports.
32+
* -[ ] [Express](https://expressjs.com/)
33+
* -[ ] Node:[http](https://nodejs.org/docs/v22.18.0/api/http.html)
34+
35+
### Logging
36+
Let's step up our logging capability with an advanced logger:
37+
* -[ ] [Winston](https://github.com/winstonjs/winston?tab=readme-ov-file#winston)
38+
* -[ ] [Pino](https://github.com/pinojs/pino?tab=readme-ov-file#pino)
39+
* -[ ] [Morgan](https://github.com/expressjs/morgan?tab=readme-ov-file#morgan)
40+
* -[ ] [Log4js](https://github.com/stritti/log4js?tab=readme-ov-file#log4js)
41+
* -[ ] [Bunyan](https://github.com/trentm/node-bunyan)

0 commit comments

Comments
 (0)