Initial contents
* Basic .gitignore * specification folder with * README.md * v1_problems.md * v2_scope.md * v2_tech_stack.md
This commit is contained in:
cliffhall
parent
d5fef7e868
commit
fb88a0c12d
4 changed files with 245 additions and 0 deletions
45
specification/README.md
Normal file
45
specification/README.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# Inspector V2 Brief
|
||||
|
||||
### Brief | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
|
||||
|
||||
## Table of Contents
|
||||
* [Motivation and Context](#motivation-and-context)
|
||||
* [Track Protocol Conformance](#track-protocol-conformance)
|
||||
* [Improve Maintainability](#improve-maintainability)
|
||||
* [Provide Extensibility](#provide-extensibility)
|
||||
* [Proper Documentation](#proper-documentation)
|
||||
|
||||
## Motivation and Context
|
||||
|
||||
The existing Inspector is hard to maintain for a number of reasons. We decided to create a more maintainable Inspector
|
||||
from the ground up, that retains the deterministic boundary of operation, but exposes a plugin architecture.
|
||||
|
||||
## Track Protocol Conformance
|
||||
* Identify any gaps in V1 inspector
|
||||
* Track which features are covered
|
||||
* Implement to parity and fill gaps
|
||||
* Provide conformance testing in CI
|
||||
|
||||
## Improve Maintainability
|
||||
* Clearer separation of concerns
|
||||
* Smaller, reusable components
|
||||
|
||||
## Provide Extensibility
|
||||
* Plugin SDK / API
|
||||
* Third parties cand develop/maintain their own plugins for features such as
|
||||
* LLM usage
|
||||
* Evals
|
||||
* Multiple server connections
|
||||
* Apps playground
|
||||
* Testing of registry configuration
|
||||
* Interface with registry
|
||||
|
||||
## Proper Documentation
|
||||
* One big README won't cut it anymore
|
||||
* Published documentation in MDX should
|
||||
* Render in style of spec
|
||||
* Kept up to date
|
||||
* Cover all features
|
||||
* Discuss troubleshooting strategies
|
||||
* Provide detailed contribution guidance that explains architecture and expected idioms
|
||||
|
||||
59
specification/v1_problems.md
Normal file
59
specification/v1_problems.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
# Inspector V1 Problems
|
||||
|
||||
### [Brief](README.md) | V1 Problems | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
|
||||
|
||||
## Table of Contents
|
||||
* [Monolithic components](#monolithic-components)
|
||||
* [Monolithic hooks](#monolithic-hooks)
|
||||
* [Environment variable explosion](#environment-variable-explosion-)
|
||||
* [Disparate OAuth flows](#disparate-oauth-flows-)
|
||||
* [CLI version combined with UI version](#cli-version-combined-with-ui-version-)
|
||||
|
||||
## Monolithic components
|
||||
* Hard to read and maintain
|
||||
* Deeply custom:
|
||||
* Divs all the way down,
|
||||
* Strewn with hundreds of css classes
|
||||
### Solution
|
||||
* Make a kit of small, reusable components that are already styled for use anywhere in the app
|
||||
* Easier to reason about than inline-customized primitives
|
||||
* Minimize css for inline customization
|
||||
* Only pass state
|
||||
* Define functions to use as handlers rather than writing inline in code
|
||||
* Makes component instantiation markup smaller and easier to understand
|
||||
* Separates code from markup
|
||||
|
||||
## Monolithic hooks
|
||||
* E.g., `useConnection` is nearly 1k lines long
|
||||
|
||||
### Solution
|
||||
* Extract inline logic out to function libraries / classes that are easier to reason about and test in isolation
|
||||
|
||||
## Environment variable explosion
|
||||
* We have a configuration file but it is for servers, not things like request timeouts, etc
|
||||
* The addition of a new environment variable for everything someone wants to configure is problematic.
|
||||
* It’s easy to misspell the variable name and the names
|
||||
* Often not named in the best way
|
||||
* Lots of touch points to update for a new variable
|
||||
|
||||
### Solution
|
||||
* A JSON configuration file would be a better approach.
|
||||
* Hierarchical groups of settings could be used
|
||||
* Different files for different configurations
|
||||
* Expanding the format to include other settings
|
||||
* A configuration file could be validated, so misspelled keys would be caught at startup
|
||||
|
||||
## Disparate OAuth flows
|
||||
* We often have deviations of behavior between basic flow, quick flow, and guided flow
|
||||
* Each flow has independent code paths that can break or behave differently from the others
|
||||
|
||||
### Solution
|
||||
* Use a single auth flow mechanism that operates in all three states while supporting different configurations
|
||||
|
||||
## CLI version combined with UI version
|
||||
* Both projects are not kept in parity and do not share significant overlap as to belong in the same repo
|
||||
|
||||
### Solution
|
||||
* Refactor/extract the CLI Inspector to a separate repo for ongoing development
|
||||
|
||||
|
||||
100
specification/v2_scope.md
Normal file
100
specification/v2_scope.md
Normal file
|
|
@ -0,0 +1,100 @@
|
|||
# Inspector V2 Scope
|
||||
|
||||
### [Brief](README.md) | [V1 Problems](v1_problems.md) | V2 Scope | [V2 Tech Stack](v2_tech_stack.md)
|
||||
|
||||
## Table of Contents
|
||||
* [Protocol Features](#protocol-features)
|
||||
* [OAuth Handling](#oauth-handling)
|
||||
* [Transport Types](#transport-types)
|
||||
* [Connection Type](#connection-type)
|
||||
* [Logging Level Control](#logging-level-control)
|
||||
* [Copy Server configuration](#copy-server-configuration)
|
||||
* [Custom Auth-related properties](#custom-auth-related-properties)
|
||||
* [Timeout management](#timeout-management)
|
||||
* [Schema parsing for Elicitation, Tool Input Schemas](#schema-parsing-for-elicitation-tool-input-schemas)
|
||||
* [Form inputs vs JSON editor for:](#form-inputs-vs-json-editor-for)
|
||||
* [Proxy server](#proxy-server)
|
||||
* [Previous Security Fixes](#previous-security-fixes)
|
||||
* [Server file maintenance](#server-file-maintenance)
|
||||
* [Plugin architecture](#plugin-architecture)
|
||||
|
||||
## Protocol Features
|
||||
* Tools
|
||||
* Resources
|
||||
* Resource Subscriptions
|
||||
* Resource Templates
|
||||
* Prompts
|
||||
* Elicitation
|
||||
* Sampling with stubbed response
|
||||
* Roots
|
||||
* Logging
|
||||
* Completions
|
||||
* Metadata
|
||||
* Pagination
|
||||
* resources/list
|
||||
* resources/templates/list
|
||||
* prompts/list
|
||||
* tools/list
|
||||
* Cancellation (of in progress requests)
|
||||
* Ping
|
||||
|
||||
## OAuth Handling
|
||||
* Quick Flow
|
||||
* Guided Flow
|
||||
* Basic (non debugger) Flow
|
||||
|
||||
## Transport Types
|
||||
* STDIO
|
||||
* SSE
|
||||
* SHTTP
|
||||
|
||||
## Connection Type
|
||||
* Direct
|
||||
* Via Proxy
|
||||
|
||||
## Logging Level Control
|
||||
* Present and synchronized when connecting to server with logging capability
|
||||
|
||||
## Copy Server configuration
|
||||
* As config file server entry
|
||||
* As config file containing server entry
|
||||
|
||||
## Custom Auth-related properties
|
||||
* Custom headers
|
||||
* Client ID
|
||||
* Secret
|
||||
* Scope
|
||||
|
||||
## Timeout management
|
||||
* Request timeout
|
||||
* Request timeout on progress (bool)
|
||||
* Maximum total timeout
|
||||
|
||||
## Schema parsing for Elicitation, Tool Input Schemas
|
||||
* New enum types
|
||||
* anyOf /oneOf
|
||||
* $ref
|
||||
* $defs
|
||||
|
||||
## Form inputs vs JSON editor for:
|
||||
* Elicitation, tool input, resource template, and prompt vars, sampling response
|
||||
* Field types of primitive, object, array
|
||||
* Nullable field types
|
||||
* Defaults
|
||||
|
||||
## Proxy server
|
||||
* Required for testing STDIO servers and HTTP servers that can’t open up their CORS origin for testing
|
||||
* Implement a feature configuration file rather than disparate environment variables for everything
|
||||
* Handle auth flows instead of browser when "via proxy" connection type selected
|
||||
|
||||
## Previous Security Fixes
|
||||
* Unique proxy server session token to prevent unauthorized access to the proxy server's ability to execute local processes and connect to MCP servers.
|
||||
* Bind to localhost by default to prevent DNS rebinding attacks (never 0.0.0.0)
|
||||
* Fix/validate redirect urls for http/https scheme only in auth flow
|
||||
|
||||
## Server file maintenance
|
||||
* Opening screen similar to MCPJam servers list
|
||||
* Adding, changing, and deleting a server would hit endpoints on the proxy server update the inspector’s servers.json config file
|
||||
|
||||
## Plugin architecture
|
||||
* 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
|
||||
41
specification/v2_tech_stack.md
Normal file
41
specification/v2_tech_stack.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Inspector V2 Tech Stack
|
||||
|
||||
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | V2 Tech Stack
|
||||
|
||||
## Table of Contents
|
||||
* [Web Client](#web-client)
|
||||
* [Language and Framework](#language-and-framework)
|
||||
* [Components and theme](#components-and-theme)
|
||||
* [Proxy Server](#proxy-server)
|
||||
* [Language and Runtime](#language-and-runtime)
|
||||
* [Transport Operation](#server)
|
||||
* [Logging](#logging)
|
||||
|
||||
|
||||
## Web Client
|
||||
### Language and Framework
|
||||
* Typescript
|
||||
* React
|
||||
|
||||
### Components and Theme
|
||||
Let's choose a feature-rich component set with easy theming control
|
||||
* -[ ] [Mantine](https://ui.mantine.dev/)
|
||||
* -[ ] [Shadcdn](https://ui.shadcn.com/)
|
||||
|
||||
## Proxy Server
|
||||
### Language and Runtime
|
||||
* Typescript
|
||||
* Node
|
||||
|
||||
### Transport Operation
|
||||
Let's consider how to operate the server transports.
|
||||
* -[ ] [Express](https://expressjs.com/)
|
||||
* -[ ] Node:[http](https://nodejs.org/docs/v22.18.0/api/http.html)
|
||||
|
||||
### Logging
|
||||
Let's step up our logging capability with an advanced logger:
|
||||
* -[ ] [Winston](https://github.com/winstonjs/winston?tab=readme-ov-file#winston)
|
||||
* -[ ] [Pino](https://github.com/pinojs/pino?tab=readme-ov-file#pino)
|
||||
* -[ ] [Morgan](https://github.com/expressjs/morgan?tab=readme-ov-file#morgan)
|
||||
* -[ ] [Log4js](https://github.com/stritti/log4js?tab=readme-ov-file#log4js)
|
||||
* -[ ] [Bunyan](https://github.com/trentm/node-bunyan)
|
||||
Loading…
Reference in a new issue