From aa97d655aa775054384c820aca90369a009da5f0 Mon Sep 17 00:00:00 2001 From: Jerome Date: Tue, 10 Jun 2025 13:27:47 +0100 Subject: [PATCH] Initial prompts / design doc with claude --- .gitignore | 1 + docs/clarifying_questions.md | 64 ++++++++++++++++++++++++++++++++++++ docs/design_doc.md | 36 ++++++++++++++++++++ docs/initial_prompt.md | 11 +++++++ 4 files changed, 112 insertions(+) create mode 100644 .gitignore create mode 100644 docs/clarifying_questions.md create mode 100644 docs/design_doc.md create mode 100644 docs/initial_prompt.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ae65225 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +reference_info/ \ No newline at end of file diff --git a/docs/clarifying_questions.md b/docs/clarifying_questions.md new file mode 100644 index 0000000..bec1cee --- /dev/null +++ b/docs/clarifying_questions.md @@ -0,0 +1,64 @@ +Clarifying Questions + +1. Project Scope & Architecture + +- Should this be a single-page React app, or do you prefer a specific build setup (Vite, Create React App, Next.js)? + - I'm okay with a build step - however I would like to have it statically served - so I'm not interested in the server components / server-side functionality of any of those frameworks. +- Do you want TypeScript throughout, or are you open to JavaScript? + - TypeScript throughout please +- Any preference for CSS approach (CSS modules, styled-components, Tailwind, etc.)? + - Preference for Tailwind + +2. Multi-Server Connection Management + +- How should users add/manage multiple MCP server connections? Through a UI form, config file, or both? + - UI form. I think that we should have the left hand side of the UI be all about MCP functionality (server statuses, debugging, MCP message trace even) and the right hand side being the chat window. I would like things to be as modular as possible so that we can refactor the UI as needed. +- Should connections be persistent across browser sessions, or reset on each visit? + - Like the MCP sessions? I think it would be cool to have sessions persist if it's shttp. For SSE that's not an option (as the session technically ends with the SSE connection) +- Do you want a dashboard view showing all connected servers, or focus on the conversational interface? + - Yes please - I think this would be good, it should show what's going on with MCP under the hood. + +3. OpenRouter Integration + +- Should we implement the full OpenRouter OAuth flow immediately, or start with a simpler approach (like API key input) and add OAuth later? + - I think we could start with an API key input if that's easier, as our useContext provider should be pluggable +- Do you want to support other inference providers from the start, or focus on OpenRouter first? + - I would like to support other providers pretty soon after writing this - we should only start with OpenRouter for now, but make sure our interfaces abstract this away. +- Any preference for model selection UX (dropdown, autocomplete, etc.)? + - Dropdown for model selection. + +4. Conversation & Agent Loop + +- How should we handle concurrent conversations across multiple servers? Separate tabs, unified view, or separate windows? + - Have tabs in the SPA, this functionality isn't super important to start with, however it would be nice if our code accounts for multiple ongoing conversations from the outset +- For the agent loop: should we show tool calls in real-time as they execute, or just show final results? + - It would be nice to show the toolcall block (while we await the result), and then show the result when it arrives. The user should see what the tool call parameters are. +- Any preference for message persistence strategy (localStorage, IndexedDB, external storage)? + - Up to you - whatever is easiest + +5. MCP Server Discovery & Connection + +- Should we implement both HTTP and stdio transports from the start, or focus on HTTP for browser deployment? + - We will never support stdio from this application. We only want the SSE and SHTTP transports. +- Do you want support for unauthenticated MCP servers, or should everything go through OAuth flows? + - We should allow for unauthed MCP servers. +- Any specific error handling/retry strategies you prefer? + - Clear error messages on failure for now is enough. We can think about strengthening this later. + +6. Development Approach + +- Would you prefer to build this incrementally (start with basic connection + chat, then add multi-server, then agent loop)? + - Incremental is preferred, I think we can try build out the components first - i.e. the inference provider abstraction, the mcp connection (maybe with something like use-mcp but supporting multiple servers), the agent loop (it would be nice to have the agent loop as a modular hook also, maybe passed in via a provider also) +- Should we create reusable components that could be published as a library later, or focus on the specific app? + - Keep this in mind for modularity, but it is not a goal at this point. +- Any testing preferences (unit tests, integration tests, manual testing only)? + - I would like the modular components to have unit tests and integration tests. + +7. Deployment & Hosting + +- Since this is statically served, any preference for deployment target (Vercel, Netlify, GitHub Pages, etc.)? + - Let's not worry about this now - ideally it wouldn't affect our design choices. +- Should we set up CI/CD from the start, or handle that later? + - Handle that later - what is important is that it is easy to set things up and run tests. + +These clarifications will help ensure the implementation matches your vision and requirements exactly. \ No newline at end of file diff --git a/docs/design_doc.md b/docs/design_doc.md new file mode 100644 index 0000000..73126d2 --- /dev/null +++ b/docs/design_doc.md @@ -0,0 +1,36 @@ +# Example Remote MCP Client + +The goal of this project is to build an example remote MCP client. This should serve two purposes: +* Provide a public example implementation of MCP features for an MCP client +* Be a prototyping testbed for incoming MCP protocol changes (when paired with the existing example-remote-server project) + +Some key technical properties of this are: +* It should be statically served, using open router's oauth-authenticated inference api +* It should have a conversational UI, with local storage for persistence + * We need to support tool calling in the assistant turn, so it will need an agent loop +* It should make MCP connections directly from the browser +* It should support connection to many MCP servers simultaneously +* It should suuport the remote MCP oauth flows + + +## React + +I think using React on the FE will be the best option. I'm not very opinionated about this, however there is a good reference library for mcp in react called [use-mcp](https://github.com/geelen/use-mcp) that might serve for good inspiration (a core limitation of this library is that the hook only supports a single MCP server) as it implements the oauth flows. + +## Inference + +We should use OpenRouter for inference, however we should try decouple the agent loop from open router directly. I think it would be good to have an InferenceProvider style react interface where we can use useContext to inherit an object that allows for inference (with tool invocations). It should also provide a llm list available from the current provider. This would mean that as other inference providers (like Anthropic/OpenAI/Google allow access to their api's via oauth users can leverage existing subscriptions/payment options instead of needing to sign up to OpenRouter). + +## Conversations & Agent loop + +We will want to allow for many conversations at once, each potentially running inference / tool calls concurrently. We should have some abstraction over persistence incase we want the messages to be stored somewhere other than local storage. + +The agent loop should run inference via the inference context/provider mentioned above, with all MCP tools added as tools the LLM can call. If a response comes back with a tool call in it, we need to evaluate the tool call, add the tool result to the message list so far, and start running inference again. This should happen until the model decides not to call a tool + +There should be a stop button that allows the user to interrupt the model + +We don't need to support message streaming - just having an indication that the agent loop is running is enough, and when a conversation turn (or tool call finishes) in the agent loop we can present that. + +## General note + +This should be nice and modular - it will be a testbed for new features, so code that is well decoupled and extensible is key. \ No newline at end of file diff --git a/docs/initial_prompt.md b/docs/initial_prompt.md new file mode 100644 index 0000000..5a50c52 --- /dev/null +++ b/docs/initial_prompt.md @@ -0,0 +1,11 @@ +Please read over docs/design_doc.md, we're going to be implementing this project. + +Please read over the mcp specification docs (cloned at reference_info/modelcontextprotocol/docs/specification), specifically at the transports and auth + +Please have a look at how auth and transports are implemented (on the client side) in the typescript-sdk (cloned at reference_info/typescript-sdk) + +When we get to implementing the inference provider, have a look at the openrouter docs (copied here reference_info/open_router_oauth_docs.md), and use fetch/websearch to figure out any other things you might need. + +Also - note that use-mcp is cloned to reference_info/use-mcp for reference. + +Once you've had a read through all of this, I'd like you to ask me any follow up questions / ambiguities with the project that you'd like resolved before we start implementing. \ No newline at end of file