goal.md

goal.md

@@ -0,0 +1,42 @@
+Build an MCP (Model Context Protocol) server dedicated to providing LSP (Language Server Protocol) capabilities to Agents. Users can specify the LSP executable path and additional arguments via parameters; the MCP server is responsible for launching the LSP server and fully utilizing and exposing MCP capabilities.
+
+### I. General Architecture
+
+Use Effect and TypeScript. Specifically, `effect/unstable/ai` and `effect/unstable/cli` provide ready-to-use implementations of MCP and CLI functionality. For LSP, you will progressively implement a bridge between `vscode-language*` and Effect inside `lsp/`. Users can launch the MCP server in stdio mode via `--stdio`, or in HTTP mode via `--http <port>`. Users directly specify the remaining arguments required to run the LSP server via command-line flags; one MCP process corresponds to one LSP server instance.
+
+### II. LSP and MCP Integration Paradigm
+
+There is a fundamental paradigm conflict between LSP and MCP. The mental model of LSP is built upon a persistent, stateful rich client, whereas MCP / Agents operate on discrete, stateless, intent-oriented tool calls and capabilities. Therefore, this MCP server cannot act as a mere proxy or forwarder; it must function as a headless virtual editor without sacrificing a lightweight architecture, MCP's native mental model, or the actual needs of Agents.
+
+For example, regarding document synchronization, the MCP server may need to implement on-demand `didOpen`, change detection, and LRU eviction mechanisms. For core capabilities, it must reconcile the tension between LSP's "push-oriented" nature and MCP/Agent's "pull-oriented" nature, handling listeners and subscriptions appropriately. Furthermore, it must smooth over complex client capability negotiations, disable unnecessary capabilities, and carefully manage positions and character encodings. This is precisely why Effect was chosen: Effect makes it possible to keep complex architectures elegant and concise.
+
+In this regard, you have full decision-making authority. Strive to design a well-engineered LSP MCP, bring your maximum intellect to bear, deliver first-class quality, and blow away the dime-a-dozen, subpar LSP MCPs out there.
+
+### III. Library Reuse
+
+Effect already exports `effect/unstable/ai` and `effect/unstable/cli` for building CLI and MCP servers. For LSP, you should use packages like `vscode-language*`, strictly confining the boundary of conversions between `vscode-language*` and Effect to `src/lsp/`, keeping the outside pure Effect code. Inside `lsp/`, you only need to progressively implement what is actually used, rather than building an exhaustive glue layer or converter from `vscode-language*` to Effect. Only write what you need.
+
+I have no doubt in your ability to demonstrate consummate mastery of Effect: maximize its features to build a highly robust system. Make the fullest use of MCP's Tools and Resources features (do not touch the Prompts feature; I consider it useless).
+
+### IV. Requirements
+
+The following requirements are non-negotiable baselines and must be strictly followed:
+
+1. **Architectural Requirements:** The overall architecture must be concise. If architectural components sum to zero in a "vector sum", that indicates a dirty, over-complicated design that should be discarded. We always pursue "minimum energy"—here, "minimum energy" means the simplest interface design required to solve the problem. Some people foolishly take instructions too literally: when told not to touch the Prompts feature, they engineer an elaborate architecture just to ensure Prompts cannot be introduced. That shows zero grasp of how to design the simplest, Occam's-razor-aligned, first-principles, KISS-oriented architecture. You are different: as a state-of-the-art assistant, you possess fundamental, exceptional insight into this.
+2. **Code Style Requirements:** This is a fundamental requirement. All code must follow Effect best practices, upholding extreme conciseness, elegance, and code aesthetics—this is your moment to shine. Once the architecture is solved, writing code is easy; truly reflecting deep insight and pursuit of code aesthetics in every line is what demonstrates your true capability.
+3. **Reuse Requirements:** Be cautious about reinventing the wheel. In reality, much of the groundwork has already been laid: you do not need to dive deep into implementing LSP specs or MCP specs from scratch, as libraries already handle them. Your primary intellectual effort should be spent on elegantly reusing and composing these libraries.
+4. **Testing Requirements:** Unit tests must not be bloated and tedious. A unit test that merely re-verifies the literal step-by-step execution written in code is not a good unit test—if code didn't execute literally, the world would crumble. The true purpose of unit tests is to verify code intent, not implementation steps; meaningful unit tests have never been about sheer breadth of coverage.
+
+### V. Context
+
+Our repository uses `scripts/repos/` to maintain the `effect` codebase directly under `repos/effect/` (the officially recommended approach by Effect), allowing you to easily read the Effect source code and understand how it works without digging into `node_modules` and wasting intellect de-obfuscating code. The repository `microsoft/language-server-protocol` is also prepared under `repos/lsp`, where specifications can be viewed under `repos/lsp/_specifications`. In addition, you are allowed to use Exa tools for web searches (do not use other web search tools) and use `curl` to directly read web page content. For the latter, a handy tip is prefixing URLs with `https://defuddle.md/` to get clean Markdown versions of web pages. Avoid scraping raw HTML pages as much as possible to save context window tokens.
+
+If there are any open-ended questions or unknown unknowns, feel free to ask me via user questions before making decisions.
+
+### VI. Workflow
+
+I encourage you to create and maintain `CLAUDE.md` to reduce the ramp-up cost for agents on each task launch, e.g., telling upcoming agents what stuff like files or documents worth or not worth reading and what's the status of this repo. I do not want you to use memory features. I do not want you to use subagents or plan mode—just do the work yourself. When a milestone or phase is completed, you may provide a prompt for me to pass to a fresh agent with a blank context window to take over your work; you do not need to finish everything in a single session. Before this MCP is completed, this document may serve as a partial source of truth. However, once everything is finished, this document should no longer be a source of truth. Good code always serves as a sufficiently comprehensive source of truth that can be easily understood without relying on external state.
+
+Use `jj commit -m` to create commits for each chunk of changes. The `jj-vcs` skill is for reference only; in most cases, you will not need it. Do not use `git`. Before committing, in addition to running unit tests and type checks, run `pnpm biome check --write --unsafe`. It might modify your code; despite the `--unsafe` flag, these changes are always safe, so you do not need to double-check what it modified.
+
+You do not need to worry about packaging or bundling the project.