@neocode-ai/web 1.1.1

package/src/content/docs/lsp.mdx

@@ -0,0 +1,188 @@
+---
+title: LSP Servers
+description: NeoCode integrates with your LSP servers.
+---
+
+NeoCode integrates with your Language Server Protocol (LSP) to help the LLM interact with your codebase. It uses diagnostics to provide feedback to the LLM.
+
+---
+
+## Built-in
+
+NeoCode comes with several built-in LSP servers for popular languages:
+
+| LSP Server         | Extensions                                                          | Requirements                                                 |
+| ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------ |
+| astro              | .astro                                                              | Auto-installs for Astro projects                             |
+| bash               | .sh, .bash, .zsh, .ksh                                              | Auto-installs bash-language-server                           |
+| clangd             | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++                | Auto-installs for C/C++ projects                             |
+| csharp             | .cs                                                                 | `.NET SDK` installed                                         |
+| clojure-lsp        | .clj, .cljs, .cljc, .edn                                            | `clojure-lsp` command available                              |
+| dart               | .dart                                                               | `dart` command available                                     |
+| deno               | .ts, .tsx, .js, .jsx, .mjs                                          | `deno` command available (auto-detects deno.json/deno.jsonc) |
+| elixir-ls          | .ex, .exs                                                           | `elixir` command available                                   |
+| eslint             | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue                  | `eslint` dependency in project                               |
+| fsharp             | .fs, .fsi, .fsx, .fsscript                                          | `.NET SDK` installed                                         |
+| gleam              | .gleam                                                              | `gleam` command available                                    |
+| gopls              | .go                                                                 | `go` command available                                       |
+| hls                | .hs, .lhs                                                           | `haskell-language-server-wrapper` command available          |
+| jdtls              | .java                                                               | `Java SDK (version 21+)` installed                           |
+| kotlin-ls          | .kt, .kts                                                           | Auto-installs for Kotlin projects                            |
+| lua-ls             | .lua                                                                | Auto-installs for Lua projects                               |
+| nixd               | .nix                                                                | `nixd` command available                                     |
+| ocaml-lsp          | .ml, .mli                                                           | `ocamllsp` command available                                 |
+| oxlint             | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | `oxlint` dependency in project                               |
+| php intelephense   | .php                                                                | Auto-installs for PHP projects                               |
+| prisma             | .prisma                                                             | `prisma` command available                                   |
+| pyright            | .py, .pyi                                                           | `pyright` dependency installed                               |
+| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru                                           | `ruby` and `gem` commands available                          |
+| rust               | .rs                                                                 | `rust-analyzer` command available                            |
+| sourcekit-lsp      | .swift, .objc, .objcpp                                              | `swift` installed (`xcode` on macOS)                         |
+| svelte             | .svelte                                                             | Auto-installs for Svelte projects                            |
+| terraform          | .tf, .tfvars                                                        | Auto-installs from GitHub releases                           |
+| tinymist           | .typ, .typc                                                         | Auto-installs from GitHub releases                           |
+| typescript         | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts                        | `typescript` dependency in project                           |
+| vue                | .vue                                                                | Auto-installs for Vue projects                               |
+| yaml-ls            | .yaml, .yml                                                         | Auto-installs Red Hat yaml-language-server                   |
+| zls                | .zig, .zon                                                          | `zig` command available                                      |
+
+LSP servers are automatically enabled when one of the above file extensions are detected and the requirements are met.
+
+:::note
+You can disable automatic LSP server downloads by setting the `NEOCODE_DISABLE_LSP_DOWNLOAD` environment variable to `true`.
+:::
+
+---
+
+## How It Works
+
+When neocode opens a file, it:
+
+1. Checks the file extension against all enabled LSP servers.
+2. Starts the appropriate LSP server if not already running.
+
+---
+
+## Configure
+
+You can customize LSP servers through the `lsp` section in your neocode config.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "lsp": {}
+}
+```
+
+Each LSP server supports the following:
+
+| Property         | Type     | Description                                       |
+| ---------------- | -------- | ------------------------------------------------- |
+| `disabled`       | boolean  | Set this to `true` to disable the LSP server      |
+| `command`        | string[] | The command to start the LSP server               |
+| `extensions`     | string[] | File extensions this LSP server should handle     |
+| `env`            | object   | Environment variables to set when starting server |
+| `initialization` | object   | Initialization options to send to the LSP server  |
+
+Let's look at some examples.
+
+---
+
+### Environment variables
+
+Use the `env` property to set environment variables when starting the LSP server:
+
+```json title="neocode.json" {5-7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "lsp": {
+    "rust": {
+      "env": {
+        "RUST_LOG": "debug"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Initialization options
+
+Use the `initialization` property to pass initialization options to the LSP server. These are server-specific settings sent during the LSP `initialize` request:
+
+```json title="neocode.json" {5-9}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "lsp": {
+    "typescript": {
+      "initialization": {
+        "preferences": {
+          "importModuleSpecifierPreference": "relative"
+        }
+      }
+    }
+  }
+}
+```
+
+:::note
+Initialization options vary by LSP server. Check your LSP server's documentation for available options.
+:::
+
+---
+
+### Disabling LSP servers
+
+To disable **all** LSP servers globally, set `lsp` to `false`:
+
+```json title="neocode.json" {3}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "lsp": false
+}
+```
+
+To disable a **specific** LSP server, set `disabled` to `true`:
+
+```json title="neocode.json" {5}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "lsp": {
+    "typescript": {
+      "disabled": true
+    }
+  }
+}
+```
+
+---
+
+### Custom LSP servers
+
+You can add custom LSP servers by specifying the command and file extensions:
+
+```json title="neocode.json" {4-7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "lsp": {
+    "custom-lsp": {
+      "command": ["custom-lsp-server", "--stdio"],
+      "extensions": [".custom"]
+    }
+  }
+}
+```
+
+---
+
+## Additional Information
+
+### PHP Intelephense
+
+PHP Intelephense offers premium features through a license key. You can provide a license key by placing (only) the key in a text file at:
+
+- On macOS/Linux: `$HOME/intelephense/licence.txt`
+- On Windows: `%USERPROFILE%/intelephense/licence.txt`
+
+The file should contain only the license key with no additional content.

package/src/content/docs/mcp-servers.mdx

@@ -0,0 +1,511 @@
+---
+title: MCP servers
+description: Add local and remote MCP tools.
+---
+
+You can add external tools to NeoCode using the _Model Context Protocol_, or MCP. NeoCode supports both local and remote servers.
+
+Once added, MCP tools are automatically available to the LLM alongside built-in tools.
+
+---
+
+#### Caveats
+
+When you use an MCP server, it adds to the context. This can quickly add up if you have a lot of tools. So we recommend being careful with which MCP servers you use.
+
+:::tip
+MCP servers add to your context, so you want to be careful with which ones you enable.
+:::
+
+Certain MCP servers, like the GitHub MCP server, tend to add a lot of tokens and can easily exceed the context limit.
+
+---
+
+## Enable
+
+You can define MCP servers in your [NeoCode Config](https://neo.khulnasoft.com/docs/config/) under `mcp`. Add each MCP with a unique name. You can refer to that MCP by name when prompting the LLM.
+
+```jsonc title="neocode.jsonc" {6}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "name-of-mcp-server": {
+      // ...
+      "enabled": true,
+    },
+    "name-of-other-mcp-server": {
+      // ...
+    },
+  },
+}
+```
+
+You can also disable a server by setting `enabled` to `false`. This is useful if you want to temporarily disable a server without removing it from your config.
+
+---
+
+### Overriding remote defaults
+
+Organizations can provide default MCP servers via their `.well-known/neocode` endpoint. These servers may be disabled by default, allowing users to opt-in to the ones they need.
+
+To enable a specific server from your organization's remote config, add it to your local config with `enabled: true`:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "jira": {
+      "type": "remote",
+      "url": "https://jira.example.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
+
+Your local config values override the remote defaults. See [config precedence](/docs/config#precedence-order) for more details.
+
+---
+
+## Local
+
+Add local MCP servers using `type` to `"local"` within the MCP object.
+
+```jsonc title="neocode.jsonc" {15}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-local-mcp-server": {
+      "type": "local",
+      // Or ["bun", "x", "my-mcp-command"]
+      "command": ["npx", "-y", "my-mcp-command"],
+      "enabled": true,
+      "environment": {
+        "MY_ENV_VAR": "my_env_var_value",
+      },
+    },
+  },
+}
+```
+
+The command is how the local MCP server is started. You can also pass in a list of environment variables as well.
+
+For example, here's how you can add the test [`@modelcontextprotocol/server-everything`](https://www.npmjs.com/package/@modelcontextprotocol/server-everything) MCP server.
+
+```jsonc title="neocode.jsonc"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "mcp_everything": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
+    },
+  },
+}
+```
+
+And to use it I can add `use the mcp_everything tool` to my prompts.
+
+```txt "mcp_everything"
+use the mcp_everything tool to add the number 3 and 4
+```
+
+---
+
+#### Options
+
+Here are all the options for configuring a local MCP server.
+
+| Option        | Type    | Required | Description                                                                         |
+| ------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
+| `type`        | String  | Y        | Type of MCP server connection, must be `"local"`.                                   |
+| `command`     | Array   | Y        | Command and arguments to run the MCP server.                                        |
+| `environment` | Object  |          | Environment variables to set when running the server.                               |
+| `enabled`     | Boolean |          | Enable or disable the MCP server on startup.                                        |
+| `timeout`     | Number  |          | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |
+
+---
+
+## Remote
+
+Add remote MCP servers by setting `type` to `"remote"`.
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-remote-mcp": {
+      "type": "remote",
+      "url": "https://my-mcp-server.com",
+      "enabled": true,
+      "headers": {
+        "Authorization": "Bearer MY_API_KEY"
+      }
+    }
+  }
+}
+```
+
+The `url` is the URL of the remote MCP server and with the `headers` option you can pass in a list of headers.
+
+---
+
+#### Options
+
+| Option    | Type    | Required | Description                                                                         |
+| --------- | ------- | -------- | ----------------------------------------------------------------------------------- |
+| `type`    | String  | Y        | Type of MCP server connection, must be `"remote"`.                                  |
+| `url`     | String  | Y        | URL of the remote MCP server.                                                       |
+| `enabled` | Boolean |          | Enable or disable the MCP server on startup.                                        |
+| `headers` | Object  |          | Headers to send with the request.                                                   |
+| `oauth`   | Object  |          | OAuth authentication configuration. See [OAuth](#oauth) section below.              |
+| `timeout` | Number  |          | Timeout in ms for fetching tools from the MCP server. Defaults to 5000 (5 seconds). |
+
+---
+
+## OAuth
+
+NeoCode automatically handles OAuth authentication for remote MCP servers. When a server requires authentication, NeoCode will:
+
+1. Detect the 401 response and initiate the OAuth flow
+2. Use **Dynamic Client Registration (RFC 7591)** if supported by the server
+3. Store tokens securely for future requests
+
+---
+
+### Automatic
+
+For most OAuth-enabled MCP servers, no special configuration is needed. Just configure the remote server:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-oauth-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+If the server requires authentication, NeoCode will prompt you to authenticate when you first try to use it. If not, you can [manually trigger the flow](#authenticating) with `neocode mcp auth <server-name>`.
+
+---
+
+### Pre-registered
+
+If you have client credentials from the MCP server provider, you can configure them:
+
+```json title="neocode.json" {7-11}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-oauth-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "oauth": {
+        "clientId": "{env:MY_MCP_CLIENT_ID}",
+        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
+        "scope": "tools:read tools:execute"
+      }
+    }
+  }
+}
+```
+
+---
+
+### Authenticating
+
+You can manually trigger authentication or manage credentials.
+
+Authenticate with a specific MCP server:
+
+```bash
+neocode mcp auth my-oauth-server
+```
+
+List all MCP servers and their auth status:
+
+```bash
+neocode mcp list
+```
+
+Remove stored credentials:
+
+```bash
+neocode mcp logout my-oauth-server
+```
+
+The `mcp auth` command will open your browser for authorization. After you authorize, NeoCode will store the tokens securely in `~/.local/share/neocode/mcp-auth.json`.
+
+---
+
+#### Disabling OAuth
+
+If you want to disable automatic OAuth for a server (e.g., for servers that use API keys instead), set `oauth` to `false`:
+
+```json title="neocode.json" {7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-api-key-server": {
+      "type": "remote",
+      "url": "https://mcp.example.com/mcp",
+      "oauth": false,
+      "headers": {
+        "Authorization": "Bearer {env:MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+---
+
+#### OAuth Options
+
+| Option         | Type            | Description                                                                      |
+| -------------- | --------------- | -------------------------------------------------------------------------------- |
+| `oauth`        | Object \| false | OAuth config object, or `false` to disable OAuth auto-detection.                 |
+| `clientId`     | String          | OAuth client ID. If not provided, dynamic client registration will be attempted. |
+| `clientSecret` | String          | OAuth client secret, if required by the authorization server.                    |
+| `scope`        | String          | OAuth scopes to request during authorization.                                    |
+
+#### Debugging
+
+If a remote MCP server is failing to authenticate, you can diagnose issues with:
+
+```bash
+# View auth status for all OAuth-capable servers
+neocode mcp auth list
+
+# Debug connection and OAuth flow for a specific server
+neocode mcp debug my-oauth-server
+```
+
+The `mcp debug` command shows the current auth status, tests HTTP connectivity, and attempts the OAuth discovery flow.
+
+---
+
+## Manage
+
+Your MCPs are available as tools in NeoCode, alongside built-in tools. So you can manage them through the NeoCode config like any other tool.
+
+---
+
+### Global
+
+This means that you can enable or disable them globally.
+
+```json title="neocode.json" {14}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-mcp-foo": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-foo"]
+    },
+    "my-mcp-bar": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-bar"]
+    }
+  },
+  "tools": {
+    "my-mcp-foo": false
+  }
+}
+```
+
+We can also use a glob pattern to disable all matching MCPs.
+
+```json title="neocode.json" {14}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-mcp-foo": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-foo"]
+    },
+    "my-mcp-bar": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command-bar"]
+    }
+  },
+  "tools": {
+    "my-mcp*": false
+  }
+}
+```
+
+Here we are using the glob pattern `my-mcp*` to disable all MCPs.
+
+---
+
+### Per agent
+
+If you have a large number of MCP servers you may want to only enable them per agent and disable them globally. To do this:
+
+1. Disable it as a tool globally.
+2. In your [agent config](/docs/agents#tools), enable the MCP server as a tool.
+
+```json title="neocode.json" {11, 14-18}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "my-mcp": {
+      "type": "local",
+      "command": ["bun", "x", "my-mcp-command"],
+      "enabled": true
+    }
+  },
+  "tools": {
+    "my-mcp*": false
+  },
+  "agent": {
+    "my-agent": {
+      "tools": {
+        "my-mcp*": true
+      }
+    }
+  }
+}
+```
+
+---
+
+#### Glob patterns
+
+The glob pattern uses simple regex globbing patterns:
+
+- `*` matches zero or more of any character (e.g., `"my-mcp*"` matches `my-mcp_search`, `my-mcp_list`, etc.)
+- `?` matches exactly one character
+- All other characters match literally
+
+:::note
+MCP server tools are registered with server name as prefix, so to disable all tools for a server simply use:
+
+```
+"mymcpservername_*": false
+```
+
+:::
+
+---
+
+## Examples
+
+Below are examples of some common MCP servers. You can submit a PR if you want to document other servers.
+
+---
+
+### Sentry
+
+Add the [Sentry MCP server](https://mcp.sentry.dev) to interact with your Sentry projects and issues.
+
+```json title="neocode.json" {4-8}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "sentry": {
+      "type": "remote",
+      "url": "https://mcp.sentry.dev/mcp",
+      "oauth": {}
+    }
+  }
+}
+```
+
+After adding the configuration, authenticate with Sentry:
+
+```bash
+neocode mcp auth sentry
+```
+
+This will open a browser window to complete the OAuth flow and connect NeoCode to your Sentry account.
+
+Once authenticated, you can use Sentry tools in your prompts to query issues, projects, and error data.
+
+```txt "use sentry"
+Show me the latest unresolved issues in my project. use sentry
+```
+
+---
+
+### Context7
+
+Add the [Context7 MCP server](https://github.com/upstash/context7) to search through docs.
+
+```json title="neocode.json" {4-7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+```
+
+If you have signed up for a free account, you can use your API key and get higher rate-limits.
+
+```json title="neocode.json" {7-9}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "context7": {
+      "type": "remote",
+      "url": "https://mcp.context7.com/mcp",
+      "headers": {
+        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Here we are assuming that you have the `CONTEXT7_API_KEY` environment variable set.
+
+Add `use context7` to your prompts to use Context7 MCP server.
+
+```txt "use context7"
+Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7
+```
+
+Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
+
+```md title="AGENTS.md"
+When you need to search docs, use `context7` tools.
+```
+
+---
+
+### Grep by Vercel
+
+Add the [Grep by Vercel](https://grep.app) MCP server to search through code snippets on GitHub.
+
+```json title="neocode.json" {4-7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "mcp": {
+    "gh_grep": {
+      "type": "remote",
+      "url": "https://mcp.grep.app"
+    }
+  }
+}
+```
+
+Since we named our MCP server `gh_grep`, you can add `use the gh_grep tool` to your prompts to get the agent to use it.
+
+```txt "use the gh_grep tool"
+What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool
+```
+
+Alternatively, you can add something like this to your [AGENTS.md](/docs/rules/).
+
+```md title="AGENTS.md"
+If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
+```