mcp-xray-pilot 0.10.0

package/data/docs/basic__fakedns.md

@@ -0,0 +1,202 @@
+---
+url: https://xtls.github.io/en/config/fakedns.html
+source_url: https://raw.githubusercontent.com/XTLS/Xray-docs-next/main/docs/en/config/fakedns.md
+title: FakeDNS
+category: basic
+slug: fakedns
+fetched_at: 2026-05-04T18:42:39.509Z
+---
+# FakeDNS
+
+FakeDNS obtains target domain names by forging DNS responses. It can reduce latency during DNS queries and assist transparent proxies in acquiring target domain names.
+
+::: warning
+FakeDNS may pollute the local DNS cache, causing "no network access" after Xray is closed.
+:::
+
+## FakeDNSObject
+
+`FakeDNSObject` corresponds to the `fakedns` item in the configuration file.
+
+```json
+{
+  "ipPool": "198.18.0.0/16",
+  "poolSize": 65535
+}
+```
+
+`FakeDnsObject` can also be configured as an array containing multiple FakeIP Pools. When a DNS query request is received, FakeDNS will return a set of FakeIPs derived from multiple FakeIP Pools simultaneously.
+
+```json
+[
+  {
+    "ipPool": "198.18.0.0/15",
+    "poolSize": 65535
+  },
+  {
+    "ipPool": "fc00::/18",
+    "poolSize": 65535
+  }
+]
+```
+
+> `ipPool`: CIDR
+
+FakeDNS will allocate addresses using the IP block specified in this option.
+
+> `poolSize`: int
+
+Specifies the maximum number of Domain-IP mappings stored by FakeDNS. When the number of mappings exceeds this value, mappings will be evicted according to LRU rules. Default is 65535.
+
+::: warning
+`poolSize` must be less than or equal to the total number of addresses in the `ipPool`.
+:::
+
+::: tip
+If `fakedns` is set in the `dns` item of the configuration file but `FakeDnsObject` is not configured, Xray will initialize `FakeDnsObject` based on the `queryStrategy` of the DNS component.
+
+When `queryStrategy` is `UseIP`, the initialized FakeIP Pool is equivalent to:
+
+```json
+[
+  {
+    "ipPool": "198.18.0.0/15",
+    "poolSize": 32768
+  },
+  {
+    "ipPool": "fc00::/18",
+    "poolSize": 32768
+  }
+]
+```
+
+When `queryStrategy` is `UseIPv4`, the initialized FakeIP Pool is equivalent to:
+
+```json
+{
+  "ipPool": "198.18.0.0/15",
+  "poolSize": 65535
+}
+```
+
+When `queryStrategy` is `UseIPv6`, the initialized FakeIP Pool is equivalent to:
+
+```json
+{
+  "ipPool": "fc00::/18",
+  "poolSize": 65535
+}
+```
+
+:::
+
+### How to use?
+
+FakeDNS is essentially a [DNS Server](./dns.md#serverobject) that can be used in conjunction with any DNS rules.
+
+It only works when DNS queries are routed to FakeDNS.
+
+```json
+{
+  "dns": {
+    "servers": [
+      "fakedns", // fakedns comes first
+      "8.8.8.8"
+    ]
+  },
+  "outbounds": [
+    {
+      "protocol": "dns",
+      "tag": "dns-out"
+    }
+  ],
+  "routing": {
+    "rules": [
+      {
+        "inboundTag": ["dns-in"], // Hijack DNS traffic from DNS query entry points, or hijack DNS traffic from transparent proxy inbounds.
+        "port": 53,
+        "outboundTag": "dns-out"
+      }
+    ]
+  }
+}
+```
+
+When an external DNS request enters the FakeDNS component, it returns an IP address within its `ipPool` as the fictitious resolution result for the domain and records the mapping between the domain and the fictitious IP.
+
+Additionally, you need to enable `Sniffing` on the inbound of the **client** that receives traffic to be proxied, and use `fakedns` for destination address resetting.
+
+```json
+"sniffing": {
+  "enabled": true,
+  "destOverride": ["fakedns"], // Use "fakedns", or combine with other sniffers
+  "metadataOnly": false        // When this is true, destOverride can only use fakedns
+}
+```
+
+::: warning
+If the FakeIP is not correctly reverted to the domain name, connection to the server will fail.
+:::
+
+### Using with other DNS types
+
+#### Coexisting with DNS Routing
+
+When using DNS routing (traffic splitting), to ensure `fakedns` has high priority, you need to add the same `domains` to it as you would for other DNS types.
+
+```json
+{
+  "servers": [
+    {
+      "address": "fakedns",
+      "domains": [
+        // Consistent with the content used for routing below
+        "geosite:cn",
+        "domain:example.com"
+      ]
+    },
+    {
+      "address": "1.2.3.4",
+      "domains": ["geosite:cn"],
+      "expectIPs": ["geoip:cn"]
+    },
+    {
+      "address": "1.1.1.1",
+      "domains": ["domain:example.com"]
+    },
+    "8.8.8.8"
+  ]
+}
+```
+
+#### FakeDNS Blacklist
+
+If you do not want certain domains to use FakeDNS, you can add `domains` configuration to other types of DNS servers. This gives other DNS servers higher priority than FakeDNS when matching specific domains, thereby implementing a FakeDNS blacklist mechanism.
+
+```json
+{
+  "servers": [
+    "fakedns",
+    {
+      "address": "1.2.3.4",
+      "domains": ["domain:do-not-use-fakedns.com"]
+    }
+  ]
+}
+```
+
+#### FakeDNS Whitelist
+
+If you want only certain domains to use FakeDNS, you can add `domains` configuration to `fakedns`. This gives `fakedns` higher priority than other DNS servers when matching specific domains, thereby implementing a FakeDNS whitelist mechanism.
+
+```json
+{
+  "servers": [
+    "1.2.3.4",
+    {
+      "address": "fakedns",
+      "domains": ["domain:only-this-use-fakedns.com"]
+    }
+  ]
+}
+```

package/data/docs/basic__geodata.md

@@ -0,0 +1,64 @@
+---
+url: https://xtls.github.io/en/config/geodata.html
+source_url: https://raw.githubusercontent.com/XTLS/Xray-docs-next/main/docs/en/config/geodata.md
+title: Geodata Files
+category: basic
+slug: geodata
+fetched_at: 2026-05-04T18:42:44.635Z
+---
+# Geodata Files
+
+Reloads geodata files on a schedule, and can download new `.dat` files before reloading. It is intended for cases where restarting Xray is inconvenient but geodata still needs periodic updates.
+
+Use with caution on low-memory devices.
+
+## GeodataObject
+
+```json
+{
+  "cron": "0 4 * * *",
+  "outbound": "proxy",
+  "assets": [
+    { "url": "https://example.com/geoip.dat", "file": "geoip.dat" },
+    { "url": "https://example.com/geosite.dat", "file": "geosite.dat" }
+  ]
+}
+```
+
+> `cron`: string
+
+A standard 5-field cron expression, evaluated in the local time zone of the Xray runtime environment. For example:
+
+- `"0 4 * * *"`: run every day at 04:00.
+- `"30 3 * * 1"`: run every Monday at 03:30.
+
+If omitted, the scheduled task is not enabled. If the previous task is still running, the next trigger is skipped.
+
+> `outbound`: string
+
+The outbound proxy `tag` used when downloading geodata files. If omitted, downloads go through the routing module.
+
+> `assets`: \[ [AssetObject](#assetobject) \]
+
+The list of geodata files to download and replace.
+
+If reloading fails after the download, all files replaced by this update are rolled back together.
+
+### AssetObject
+
+```json
+{
+  "url": "https://example.com/geoip.dat",
+  "file": "geoip.dat"
+}
+```
+
+> `url`: string
+
+The resource download URL. It must be an HTTPS URL.
+
+> `file`: string
+
+The resource filename to write, such as `geoip.dat` or `geosite.dat`.
+
+The file is resolved using the [Resource File Path](./features/env.md#resource-file-path). It must be an existing regular file inside the resource directory; absolute paths and paths escaping the resource directory are not supported.

package/data/docs/basic__inbound.md

@@ -0,0 +1,159 @@
+---
+url: https://xtls.github.io/en/config/inbound.html
+source_url: https://raw.githubusercontent.com/XTLS/Xray-docs-next/main/docs/en/config/inbound.md
+title: Inbound Proxy
+category: basic
+slug: inbound
+fetched_at: 2026-05-04T18:42:40.036Z
+---
+# Inbound Proxy
+
+Inbound connections are used to receive incoming data. For available protocols, please refer to [Inbound Protocols](./inbounds/).
+
+## InboundObject
+
+`InboundObject` corresponds to a child element of the `inbounds` item in the configuration file.
+
+```json
+{
+  "inbounds": [
+    {
+      "listen": "127.0.0.1",
+      "port": 1080,
+      "protocol": "protocol_name",
+      "settings": {},
+      "streamSettings": {},
+      "tag": "identifier",
+      "sniffing": {
+        "enabled": true,
+        "destOverride": ["http", "tls"]
+      }
+    }
+  ]
+}
+```
+
+> `listen`: address
+
+The listening address, which can be an IP address or a Unix domain socket. The default value is `"0.0.0.0"`, which means listening on all network interfaces.
+
+You can specify an IP address available on the system.
+
+`"::"` is equivalent to `"0.0.0.0"`; both will listen on IPv6 and IPv4 simultaneously. However, if you only want to listen on IPv6, you can set `v6only` in `sockopt` to true. If you only want to listen on IPv4, you can use commands like `ip a` to view the specific IP on the network card (usually the machine's public IP address or a private network address like 10.x.x.x) and listen on that. Of course, you can do the same for IPv6.
+
+Note that because UDP is not connection-oriented, if the inbound is based on UDP and there are multiple IP addresses on the network card, and the external connection is to a non-preferred address on the card, Xray might incorrectly use the preferred address as the source address for the reply instead of the target of the external connection, causing the connection to fail.
+The solution is not to listen on `0.0.0.0` but to listen on the specific IP address on the network card.
+
+Supports Unix domain sockets in absolute path format, such as `"/dev/shm/domain.socket"`. You can add `@` at the beginning to represent [abstract](https://www.man7.org/linux/man-pages/man7/unix.7.html), and `@@` for abstract with padding.
+
+When filling in a Unix domain socket, `port` and `allocate` will be ignored. The protocol can currently be VLESS, VMess, or Trojan, and applies only to TCP-based underlying transports, such as `tcp`, `websocket`, `grpc`. UDP-based transports like `mkcp` are not supported.
+
+When filling in a Unix domain socket, you can use the format `"/dev/shm/domain.socket,0666"`, i.e., adding a comma and access permission indicators after the socket, to specify the access permissions of the socket. This can be used to solve socket permission issues that occur by default.
+
+> `port`: number | "env:variable" | string
+
+Port. Accepted formats are as follows:
+
+- Integer value: The actual port number.
+- Environment variable: Starts with `"env:"`, followed by the name of an environment variable, such as `"env:PORT"`. Xray will parse this environment variable as a string.
+- String: Can be a numeric string, such as `"1234"`; or a numerical range, such as `"5-10"` indicating ports 5 to 10 (6 ports in total). Commas can be used for segmentation, such as `11,13,15-17` indicating port 11, port 13, and ports 15 to 17 (5 ports in total).
+
+When only one port is specified, Xray will listen for inbound connections on this port. When a port range is specified, Xray will listen on all ports within the range.
+
+Note that listening on a port is a relatively expensive operation. Listening on a port range that is too large may cause a significant increase in resource usage or even cause Xray to fail to work properly. Generally speaking, problems may begin to appear when the number of listening ports approaches four digits. If you need to use a very large range, please consider using iptables for redirection instead of setting it here.
+
+> `protocol`: "dokodemo-door" | "http" | "shadowsocks" | "socks" | "vless" | "vmess" | "trojan" | "wireguard" | "hysteria"
+
+Connection protocol name. See the list of available [Inbound Protocols](./inbounds/) on the left.
+
+> `settings`: InboundConfigurationObject
+
+Specific configuration content, which varies by protocol. See `InboundConfigurationObject` in each protocol section for details.
+
+> `streamSettings`: [StreamSettingsObject](./transport.md#streamsettingsobject)
+
+Underlying transport method (transport) is the way the current Xray node connects with other nodes.
+
+> `tag`: string
+> The identifier of this inbound connection, used to locate this connection in other configurations.
+
+::: danger
+When it is not empty, its value must be **unique** among all `tag`s.
+:::
+
+> `sniffing`: [SniffingObject](#sniffingobject)
+
+Traffic sniffing is mainly used for transparent proxies and similar purposes. A typical flow is as follows:
+
+1. If a device accesses the internet and visits abc.com, the device first queries DNS to get the IP of abc.com as 1.2.3.4, and then the device initiates a connection to 1.2.3.4.
+2. If sniffing is not configured, the connection request received by Xray is for 1.2.3.4, which cannot be used for routing traffic based on domain rules.
+3. When `enabled` in sniffing is set to `true`, Xray will sniff the domain name, i.e., abc.com, from the traffic data when processing this connection.
+4. Xray will reset 1.2.3.4 to abc.com. The routing can then divert traffic according to the domain rules.
+
+Because it becomes a connection requesting abc.com, more things can be done. Besides routing domain rule diversion, it can also re-perform DNS resolution and other tasks.
+
+When `enabled` in sniffing is set to `true`, it can also sniff Bittorrent type traffic. Then you can configure the "protocol" item in routing to set rules for handling unencrypted BT traffic. For example, the server side can be used to intercept unencrypted BT traffic, or the client side can fixedly forward BT traffic to a certain VPS, etc.
+
+Note: Newer browsers may use ECH to encrypt the Client Hello. In this case, Xray can only see the domain in the Outer Hello. You may need to consider hijacking DNS or manually disabling ECH in the browser configuration.
+
+### SniffingObject
+
+```json
+{
+  "enabled": true,
+  "destOverride": ["http", "tls", "fakedns"],
+  "metadataOnly": false,
+  "domainsExcluded": [],
+  "ipsExcluded": [],
+  "routeOnly": false
+}
+```
+
+> `enabled`: true | false
+
+Whether to enable traffic sniffing.
+
+> `destOverride`: \["http" | "tls" | "quic" | "fakedns"\]
+
+When the traffic is of the specified type, reset the destination of the current connection based on the destination address contained within it.
+
+::: tip
+Xray will only sniff the domains of protocols in `destOverride` for routing purposes. If you only want to sniff for routing but do not want to reset the destination address (e.g., resetting the destination address when using the Tor browser will cause connection failure), please add the corresponding protocol here and enable `routeOnly`.
+:::
+
+> `metadataOnly`: true | false
+
+When enabled, only the connection metadata will be used to sniff the destination address. At this time, sniffers other than `fakedns` will not be activated.
+
+If disabled (using more than just metadata to infer the destination address), the client must send data first before the proxy server actually establishes a connection. This behavior is incompatible with protocols where the server must initiate the first message, such as the SMTP protocol.
+
+> `domainsExcluded`: [string]
+
+A list of domains. If the result of traffic sniffing is in this list, the destination address will **not** be reset. The domain format is the same as in [Routing Configuration](./routing.md#ruleobject).
+
+::: tip
+Filling in some domains may solve issues with iOS push notifications, Mijia smart devices, and voice chat in certain games (Rainbow Six).<br>
+If you need to troubleshoot the cause of certain problems, you can test by disabling `"sniffing"` or enabling `"routeOnly"`.
+:::
+
+```json
+"domainsExcluded": [
+    "courier.push.apple.com", // iOS push notifications
+    "Mijia Cloud", // Mijia smart devices
+    "dlg.io.mi.com"
+]
+```
+
+> `ipsExcluded`: [string]
+
+A list of IPs. If the destination address is in this list, the destination address will **not** be reset. The format is the same as in [Routing Configuration](./routing.md#ruleobject).
+
+> `routeOnly`: true | false
+
+Use the sniffed domain only for routing; the proxy destination address remains the IP. The default value is `false`.
+
+This item requires `destOverride` to be enabled to work.
+
+::: tip
+When it is guaranteed that **the proxied connection can obtain correct DNS resolution**, using `routeOnly` while enabling `destOverride`, and setting the routing matching strategy `domainStrategy` to `AsIs`, allows for domain and IP traffic splitting without DNS resolution throughout the process. In this case, the IP used when matching IP rules is the original IP of the domain name.
+:::

package/data/docs/basic__index.md

@@ -0,0 +1,136 @@
+---
+url: https://xtls.github.io/en/config/index.html
+source_url: https://raw.githubusercontent.com/XTLS/Xray-docs-next/main/docs/en/config/index.md
+title: Configuration File
+category: basic
+slug: index
+fetched_at: 2026-05-04T18:42:37.430Z
+---
+# Configuration File
+
+> **This chapter will tell you all the details of Xray configuration. Mastering this content will allow you to unleash the greater power of Xray.**
+
+## Overview
+
+The configuration file for Xray is in JSON format. There is no difference in the configuration format between the client and the server; only the actual configuration content differs.
+The format is as follows:
+
+```json
+{
+  "version": {},
+  "log": {},
+  "api": {},
+  "dns": {},
+  "routing": {},
+  "policy": {},
+  "inbounds": [],
+  "outbounds": [],
+  "transport": {},
+  "stats": {},
+  "reverse": {},
+  "fakedns": {},
+  "metrics": {},
+  "observatory": {},
+  "burstObservatory": {},
+  "geodata": {}
+}
+```
+
+::: warning
+If you are new to Xray, you can click to view [Configuration & Run in Quick Start](../document/install.md) first to learn the most basic configuration methods, and then check the content of this chapter to master all configuration methods of Xray.
+:::
+
+::: details Click to expand: Learn how to make AI write the correct configuration file directly
+It is recommended to copy the following content and send it to the AI, which can significantly improve the usability of the generated configuration:
+
+```text
+[https://xtls.github.io/llms-full.txt](https://xtls.github.io/llms-full.txt) This link is the official full documentation of Xray-core.
+
+【Role Setting】
+You are an expert proficient in network protocols and Xray-core configuration.
+
+【Task Requirements】
+1. Knowledge Base: Please read and deeply understand the content of this link, and use it as the sole basis for answering questions and writing configurations.
+2. No Hallucinations: Absolutely do not fabricate fields that do not exist in the documentation. If the documentation does not mention it, please tell me directly "Documentation does not mention".
+3. Default Format: Although Xray supports multiple formats, please output standard JSON format configuration by default (unless I explicitly request YAML or TOML), and add key comments.
+4. Exception Handling: If you cannot access this link, please inform me clearly and prompt me to manually download the documentation and upload it to you.
+```
+
+:::
+
+## Basic Configuration Modules
+
+> version
+
+Optional. Controls the version on which this config can run. This prevents accidental running on unexpected client versions when sharing the config. The client will check if the current version matches this requirement at runtime.
+
+```json
+"version": {
+    "min": "25.8.3",
+    "max": ""
+}
+```
+
+Both `min` and `max` are optional. Not setting them or leaving them empty means no restrictions. It does not need to be an actual existing version, as long as it complies with the Xray version syntax x.y.z.
+
+25.8.3 is the version where Xray added this feature. Setting a version lower than this is meaningless (older versions will not check it).
+
+> log:[LogObject](./log.md)
+
+Log configuration, controls how Xray outputs logs.
+
+> api:[ApiObject](./api.md)
+
+Provides some API interfaces for remote calls.
+
+> dns: [DnsObject](./dns.md)
+
+Built-in DNS server. If this item is not configured, the system DNS settings are used.
+
+> routing: [RoutingObject](./routing.md)
+
+Routing function. You can set rules to divert data to be sent out from different outbounds.
+
+> policy: [PolicyObject](./policy.md)
+
+Local policy. You can set different user levels and corresponding policy settings.
+
+> inbounds: \[ [InboundObject](./inbound.md) \]
+
+An array. Each element is an inbound connection configuration.
+
+> outbounds: \[ [OutboundObject](./outbound.md) \]
+
+An array. Each element is an outbound connection configuration.
+
+> transport: [TransportObject](./transport.md)
+
+Used to configure how Xray establishes and uses network connections with other servers.
+
+> stats: [StatsObject](./stats.md)
+
+Used to configure traffic statistics.
+
+> reverse: [ReverseObject](./reverse.md)
+
+Reverse proxy. Can forward server-side traffic to the client, i.e., reverse traffic forwarding.
+
+> fakedns: [FakeDnsObject](./fakedns.md)
+
+FakeDNS configuration. Can be used with transparent proxies to obtain the actual domain name.
+
+> metrics: [metricsObject](./metrics.md)
+
+Metrics configuration. A more direct (hopefully better) way to export statistics.
+
+> observatory: [ObservatoryObject](./observatory.md#observatoryobject)
+
+Background connection observatory. Detects the connection status of outbound proxies.
+
+> burstObservatory: [BurstObservatoryObject](./observatory.md#burstobservatoryobject)
+
+Burst connection observatory. Detects the connection status of outbound proxies.
+
+> geodata: [GeodataObject](./geodata.md)
+
+Automatic update and hot reload for geodata files.

package/data/docs/basic__log.md

@@ -0,0 +1,67 @@
+---
+url: https://xtls.github.io/en/config/log.html
+source_url: https://raw.githubusercontent.com/XTLS/Xray-docs-next/main/docs/en/config/log.md
+title: Log Configuration
+category: basic
+slug: log
+fetched_at: 2026-05-04T18:42:37.922Z
+---
+# Log Configuration
+
+Log configuration controls how Xray outputs logs.
+
+Xray has two types of logs: access logs and error logs. You can configure the output method for each type independently.
+
+## LogObject
+
+`LogObject` corresponds to the `log` entry in the configuration file.
+
+```json
+{
+  "log": {
+    "access": "file_path",
+    "error": "file_path",
+    "loglevel": "warning",
+    "dnsLog": false,
+    "maskAddress": ""
+  }
+}
+```
+
+> `access`: string
+
+The file path for the access log. Its value must be a valid file path, such as `"/var/log/Xray/access.log"` (Linux) or `"C:\\Temp\\Xray\\_access.log"` (Windows). When this item is unspecified or empty, logs are output to stdout.
+
+- Special value `none`: disables the access log.
+
+> `error`: string
+
+The file path for the error log. Its value must be a valid file path, such as `"/var/log/Xray/error.log"` (Linux) or `"C:\\Temp\\Xray\\_error.log"` (Windows). When this item is unspecified or empty, logs are output to stdout.
+
+- Special value `none`: disables the error log.
+
+> `loglevel`: "debug" | "info" | "warning" | "error" | "none"
+
+The level of the error log, indicating the information that needs to be recorded.
+The default value is `"warning"`.
+
+- `"debug"`: Output information used for debugging. Includes all `"info"` content.
+- `"info"`: Runtime status information, etc., which does not affect normal usage. Includes all `"warning"` content.
+- `"warning"`: Information output when issues occur that do not affect normal operation but may impact user experience. Includes all `"error"` content.
+- `"error"`: Xray encountered a problem where it cannot operate normally and requires immediate resolution.
+- `"none"`: Do not record any content.
+
+> `dnsLog`: bool
+
+Whether to enable DNS query logs, for example: `DOH//doh.server got answer: domain.com -> [ip1, ip2] 2.333ms`
+
+> `maskAddress`: "quarter" | "half" | "full"
+
+IP address mask. When enabled, it automatically replaces IP addresses appearing in the log to protect privacy when sharing logs. The default is empty (disabled).
+
+Currently, the available levels are `quarter`, `half`, and `full`. The masking formats correspond as follows:
+
+- ipv4 `1.2.*.*` `1.*.*.*` `[Masked IPv4]`
+- ipv6 `1234:5678::/32` `1234::/16` `[Masked IPv6]`
+
+For more specific requirements, you can use a custom format such as `/16+/32`. The format defines the number of bits to keep unmasked; the first number is for IPv4 and the second for IPv6. Note that the IPv4 value must be divisible by 8. Using /32 (IPv4) or /128 (IPv6) means no masking, while /0 will display as `[Masked IPv4/IPv6]`.