docs: add Xquik read context example

[kriptoburak]

Summary

• Add a ready-to-copy Xquik configuration for read-only X/Twitter MCP context.
• Link Xquik and TweetClaw from Unla's quick-start flow.
• Reject duplicate normalized router prefixes inside one MCP configuration.
• Parse and validate every shipped proxy example in tests.

Review Repairs

• Keep wildcard CORS non-credentialed.
• Allow the MCP transport's GET, POST, and DELETE methods.
• Let Unla encode structured query arguments and send Xquik's required q parameter.
• Preserve current Xquik response fields without stale response reshaping.
• Omit optional cursor parameters when empty.
• Keep default: "20" because ArgConfig.Default is a Go string.
• Mark all 4 tools read-only, non-destructive, and idempotent.
• Add sample parsing coverage to prevent invalid YAML types.

Independent Repository Fix

ValidateMCPConfig previously accepted /api and /api/ together. Both normalize to the same route, so hot updates could create ambiguous routing. Validation now rejects this collision. Global validation also avoids reporting the same within-config collision twice.

Validation

• make test
• go test ./internal/common/config ./internal/core/... ./internal/template/...
• go vet ./...
• go build ./cmd/apiserver ./cmd/mcp-gateway ./cmd/mock-server
• git diff --check

The branch contains exactly 1 SSH-signed, GitHub-verified commit.

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.

[sourcery-ai]

Reviewer's Guide

Adds a new Unla configuration for read-only Xquik-backed X/Twitter MCP tools and links it from the main README quick-start flow, providing search, tweet lookup, user lookup, and reply-reading capabilities with credentials loaded from the runtime environment and write-like actions explicitly excluded.

Sequence diagram for xquik_search_tweets tool invocation

sequenceDiagram
  actor User
  participant MCPClient
  participant UnlaServer as Unla_xquik-read-context
  participant XquikAPI

  User ->> MCPClient: invoke tool xquik_search_tweets(query, limit)
  MCPClient ->> UnlaServer: xquik_search_tweets with args
  UnlaServer ->> UnlaServer: load env XQUIK_API_KEY
  UnlaServer ->> XquikAPI: GET /api/v1/x/tweets/search?q=query&limit=limit
  XquikAPI -->> UnlaServer: tweets, total
  UnlaServer -->> MCPClient: responseBody tweets, total
  MCPClient -->> User: display search results

Loading

File-Level Changes

Change	Details	Files
Link the new Xquik read-context example config from the main README quick-start instructions.	Add a short paragraph under the setup section pointing to the new Xquik read-context config file as a read-only social research example Clarify that write-like or recurring X/Twitter actions (posts, DMs, uploads, monitors, webhooks, giveaway draws) should stay in TweetClaw/OpenClaw for explicit user approval	README.md
Introduce a dedicated Unla config for Xquik-powered, read-only X/Twitter MCP tools.	Define a router named xquik-read-context with CORS configuration allowing GET/OPTIONS and relevant MCP headers Register a server exposing only four allowed tools: search tweets, get tweet, lookup user, and get tweet replies Load the XQUIK_API_KEY from the Unla runtime environment into a shared XAPIKey config field Configure four HTTP GET tools with Xquik API endpoints, arguments, and concise JSON-shaped responseBody templates for tweets, tweet details, user lookup, and tweet replies including pagination cursor handling	configs/proxy-xquik-read-context.yaml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 3 issues, and left some high level feedback:

• In xquik_search_tweets, the limit arg is typed as number but the default is the string "20"; consider using an unquoted numeric default to avoid type/coercion surprises.
• The xquik_get_tweet_replies endpoint always appends cursor={{.Args.cursor}}, which will send cursor= on first calls; if the template engine allows it, consider conditionally including the cursor parameter only when non-empty to avoid ambiguous query strings.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `xquik_search_tweets`, the `limit` arg is typed as `number` but the default is the string "20"; consider using an unquoted numeric default to avoid type/coercion surprises.
- The `xquik_get_tweet_replies` endpoint always appends `cursor={{.Args.cursor}}`, which will send `cursor=` on first calls; if the template engine allows it, consider conditionally including the cursor parameter only when non-empty to avoid ambiguous query strings.

## Individual Comments

### Comment 1
<location path="configs/proxy-xquik-read-context.yaml" line_range="14-23" />
<code_context>
+  - server: "xquik-read-context"
+    prefix: "/gateway/xquik"
+    cors:
+      allowOrigins:
+        - "*"
+      allowMethods:
+        - "GET"
+        - "OPTIONS"
+      allowHeaders:
+        - "Content-Type"
+        - "Authorization"
+        - "Mcp-Session-Id"
+        - "mcp-protocol-version"
+      exposeHeaders:
+        - "Mcp-Session-Id"
+        - "mcp-protocol-version"
+      allowCredentials: true
+
+servers:
</code_context>
<issue_to_address>
**issue (bug_risk):** CORS configuration uses `allowOrigins: "*"` with `allowCredentials: true`, which is invalid per the CORS spec and may be ignored by browsers.

With `allowCredentials: true`, the CORS response must use a specific origin value, not `*`. Browsers will reject this combination. Please either (a) restrict `allowOrigins` to the expected origins, or (b) set `allowCredentials: false` if you truly need `*` and can do without credentials.
</issue_to_address>

### Comment 2
<location path="configs/proxy-xquik-read-context.yaml" line_range="41-46" />
<code_context>
+  - name: "xquik_search_tweets"
+    description: "Search public X/Twitter posts for source context before drafting or analysis"
+    method: "GET"
+    endpoint: "https://xquik.com/api/v1/x/tweets/search?q={{.Args.query}}&limit={{.Args.limit}}"
+    headers:
+      X-API-Key: "{{.Config.XAPIKey}}"
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Query parameters are interpolated without URL encoding, which can break the request for complex queries.

`.Args.query` may include spaces or characters like `#` and `@` that must be URL-encoded (e.g., `q=from:foo bar` will produce an invalid URL). Use a URL-encoding helper in the template (e.g., `{{ urlquery .Args.query }}` or equivalent) for this and any other query parameters to prevent malformed requests.

```suggestion
  - name: "xquik_search_tweets"
    description: "Search public X/Twitter posts for source context before drafting or analysis"
    method: "GET"
    endpoint: "https://xquik.com/api/v1/x/tweets/search?q={{ urlquery .Args.query }}&limit={{ urlquery .Args.limit }}"
    headers:
      X-API-Key: "{{.Config.XAPIKey}}"
```
</issue_to_address>

### Comment 3
<location path="configs/proxy-xquik-read-context.yaml" line_range="54-59" />
<code_context>
+        type: "string"
+        description: "X search syntax, keyword, account, or URL-derived query"
+        default: ""
+      - name: "limit"
+        position: "query"
+        required: false
+        type: "number"
+        description: "Maximum posts to return"
+        default: "20"
+    responseBody: |-
+      {
</code_context>
<issue_to_address>
**issue (bug_risk):** The `limit` argument is typed as `number` but the default value is a string.

Given `type: "number"` for `limit`, using a string default (`"20"`) may cause parsing or validation issues. Please change the default to a numeric literal, e.g. `default: 20`, to match the declared type.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[kriptoburak]

Addressed the Sourcery review in 65a57cc.

Changes:

• Set wildcard CORS to allowCredentials: false.
• Let Unla append and encode query-position args instead of interpolating query strings into endpoints.
• Changed limit default to a numeric value.
• Removed the always-empty cursor query from the replies endpoint so Unla only appends it when provided.

Validation rerun:

• YAML parse for configs/proxy-xquik-read-context.yaml
• git diff --check
• added-line safety scan
• go test ./...

[kriptoburak]

Published b2cd0d1 as 1 SSH-signed, GitHub-verified commit.

The original Sourcery findings remain resolved. This pass also fixed current integration drift found during an end-to-end configuration audit:

• Search now sends Xquik's required q query parameter through Unla's URL encoder.
• CORS now permits the MCP transport's GET, POST, and DELETE methods.
• Responses pass through Xquik's current JSON fields instead of reshaping them into stale total and nextCursor fields.
• All 4 tools declare read-only, non-destructive, idempotent MCP annotations.
• The numeric default remains "20" because Unla's ArgConfig.Default field is a Go string.

The independent Unla fix remains intact: single-config validation rejects normalized router-prefix collisions such as /api and /api/, while global validation avoids duplicate reports.

Validation passed: make test, targeted config/core/template tests, go vet ./..., all 3 production binary builds, and git diff --check.

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.