docs: add Xquik read context example#321
Open
kriptoburak wants to merge 1 commit into
Open
Conversation
Contributor
Reviewer's GuideAdds 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 invocationsequenceDiagram
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
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 3 issues, and left some high level feedback:
- In
xquik_search_tweets, thelimitarg is typed asnumberbut the default is the string "20"; consider using an unquoted numeric default to avoid type/coercion surprises. - The
xquik_get_tweet_repliesendpoint always appendscursor={{.Args.cursor}}, which will sendcursor=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>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>
kriptoburak
force-pushed
the
codex/xquik-read-context-example
branch
from
7705032 to
65a57cc
Compare
Author
|
Addressed the Sourcery review in Changes:
Validation rerun:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why
Unla already shows how to map REST APIs into MCP tools. This adds a concrete social-research example for search tweets, tweet lookup, user lookup, and reply reads while keeping credentials in the Unla runtime environment instead of tool arguments or prompts.
Validation
ruby -e 'require "yaml"; YAML.load_file("configs/proxy-xquik-read-context.yaml")'git diff --checkgo test ./...Known target-owned link sweep notes: the existing README currently returns 404 for the Snyk badge target and the docs quick-start URL from command-line checks, and Star History timed out. The new Xquik endpoint templates return 402 without credentials, which is expected for unauthenticated API routes.
Summary by Sourcery
Add a read-only Xquik-based X/Twitter source-context configuration and link it from the quick-start documentation.
Enhancements:
Documentation: