Skip to content

MCP: Add first wave of material, mostly indexing existing others #204

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 20, 2025

Conversation

amotl
Copy link
Member

@amotl amotl commented May 18, 2025

Copy link

coderabbitai bot commented May 18, 2025

Walkthrough

The documentation for integrations was updated to introduce a new section dedicated to the Model Context Protocol (MCP). This includes an overview page for MCP, detailed documentation for the CrateDB MCP Server, a community servers guide, and an update to the integration index to reference these new MCP resources.

Changes

File(s) Change Summary
docs/integrate/index.md Updated to include a new entry for "mcp/index" in the list of integration topics under integrations.
docs/integrate/mcp/index.md Added a new documentation page introducing the Model Context Protocol (MCP), its concepts, usage, community links, and related docs.
docs/integrate/mcp/cratedb-mcp.md Added a new documentation file describing the CrateDB MCP Server, its purpose, resources, usage example, and usage cautions.
docs/integrate/mcp/community.md Added a new documentation file outlining MCP community servers, their compatibility, configuration, and example resources.

Sequence Diagram(s)

sequenceDiagram
    User->>Integration Docs: Browse integration topics
    Integration Docs->>MCP Index: Display MCP overview and usage
    User->>MCP Index: Select CrateDB MCP Server or Community Servers
    MCP Index->>CrateDB MCP Server Docs: Show CrateDB MCP Server details and resources
    MCP Index->>Community Servers Docs: Show community servers overview and configuration
Loading

Possibly related issues

Poem

In the warren of docs, a new path appears,
MCP hops in, allaying old fears.
CrateDB and friends, now easy to find,
With guides and resources, all well-aligned.
🐇 The protocol’s here, connections anew—
Integration adventures await for you!


📜 Recent review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 717effd and 367d601.

📒 Files selected for processing (4)
  • docs/integrate/index.md (1 hunks)
  • docs/integrate/mcp/community.md (1 hunks)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
  • docs/integrate/mcp/index.md (1 hunks)
✅ Files skipped from review due to trivial changes (1)
  • docs/integrate/mcp/community.md
🚧 Files skipped from review as they are similar to previous changes (3)
  • docs/integrate/index.md
  • docs/integrate/mcp/index.md
  • docs/integrate/mcp/cratedb-mcp.md
⏰ Context from checks skipped due to timeout of 90000ms (1)
  • GitHub Check: Build docs
✨ Finishing Touches
🧪 Generate Unit Tests
  • Create PR with Unit Tests
  • Commit Unit Tests in branch mcp-first
  • Post Copyable Unit Tests in Comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share
🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

‼️ IMPORTANT
Auto-reply has been disabled for this repository in the CodeRabbit settings. The CodeRabbit bot will not respond to your replies unless it is explicitly tagged.

  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
    • @coderabbitai explain this code block.
    • @coderabbitai modularize this function.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read src/utils.ts and explain its main purpose.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
    • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

  • @coderabbitai pause to pause the reviews on a PR.
  • @coderabbitai resume to resume the paused reviews.
  • @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
  • @coderabbitai full review to do a full review from scratch and review all the files again.
  • @coderabbitai summary to regenerate the summary of the PR.
  • @coderabbitai generate docstrings to generate docstrings for this PR.
  • @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
  • @coderabbitai auto-generate unit tests to generate unit tests for this PR.
  • @coderabbitai resolve resolve all the CodeRabbit review comments.
  • @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
  • @coderabbitai help to get help.

Other keywords and placeholders

  • Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@amotl amotl requested review from bmunkholm, kneth and surister May 18, 2025 12:12
@amotl amotl marked this pull request as ready for review May 18, 2025 12:12
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (3)
docs/integrate/mcp/community.md (2)

3-4: Clarify introductory sentence.

Consider rephrasing for conciseness and consistency, e.g.:

- MCP servers that mostly use PostgreSQL adapter implementations which
- are compatible with CrateDB.
+ MCP community servers primarily use PostgreSQL adapters compatible with CrateDB.

23-27: Fix link-alt text for the Configure card.

The alternate text should describe the configuration guide rather than repeating "MCP Server landscape":

 :link: ctk:query/mcp/server
 :link-type: doc
-:link-alt: MCP Server landscape
+:link-alt: MCP Server configuration
docs/integrate/mcp/index.md (1)

8-8: Typo in toctree entry.

Correct the spelling of "Cummunity" and capitalize consistently:

- Cummunity servers <community>
+ Community servers <community>
📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 44a44ab and 6d4c810.

📒 Files selected for processing (4)
  • docs/integrate/index.md (1 hunks)
  • docs/integrate/mcp/community.md (1 hunks)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
  • docs/integrate/mcp/index.md (1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mcp/community.md

37-37: Bare URL used
null

(MD034, no-bare-urls)

docs/integrate/mcp/cratedb-mcp.md

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms (1)
  • GitHub Check: Build docs
🔇 Additional comments (3)
docs/integrate/index.md (1)

20-20: Approve addition of MCP section to the integrations index.

Inserting mcp/index between cdc/index and metrics/index correctly surfaces the new MCP guide alongside existing integrations.

docs/integrate/mcp/cratedb-mcp.md (2)

30-31: False-positive bare-URL warnings.

The markdownlint MD034 flags bare URLs here, but these are part of Sphinx/MyST :link: directives and are valid in this context. You can safely ignore MD034 for these lines.

Also applies to: 39-39, 47-47

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

30-30: Bare URL used
null

(MD034, no-bare-urls)


1-66: Comprehensive CrateDB MCP Server guide.

This new document clearly introduces the MCP Server’s purpose, installation, usage, examples, and experimental disclaimer.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
docs/integrate/mcp/community.md (1)

1-4: Enhance the introduction with more context
Consider adding a brief introductory sentence (e.g., “This section introduces popular community-run Model Context Protocol servers for PostgreSQL and CrateDB integration.”) to provide immediate context and set expectations for readers.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6d4c810 and 1d3527e.

📒 Files selected for processing (4)
  • docs/integrate/index.md (1 hunks)
  • docs/integrate/mcp/community.md (1 hunks)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
  • docs/integrate/mcp/index.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
  • docs/integrate/index.md
  • docs/integrate/mcp/cratedb-mcp.md
  • docs/integrate/mcp/index.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mcp/community.md

36-36: Bare URL used
null

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms (1)
  • GitHub Check: Build docs
🔇 Additional comments (3)
docs/integrate/mcp/community.md (3)

5-7: Grid layout syntax is consistent
The grid directive and gutter configuration align with existing MCP docs; no changes needed here.


35-43: Ignore MD034 lint for the bare URL
The GitHub examples URL is inside a directive with a :link-alt attribute. The MD034 warning is a false positive in this context.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

36-36: Bare URL used
null

(MD034, no-bare-urls)


44-45: Grid directive closure is correct
The closing :::: matches the opening directive. No changes needed.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
docs/integrate/mcp/community.md (2)

9-21: Refine wording for clarity
The phrasing “An overview about a fragment of the MCP server landscape” is a bit awkward. Consider simplifying and tightening the language for better readability.

- An overview about a fragment of the MCP server landscape,
- focusing on the most popular ones that can connect to both
- PostgreSQL and CrateDB databases.
+ An overview of the MCP server landscape, focusing on the most popular servers
+ that connect to both PostgreSQL and CrateDB.

23-34: Streamline configuration card description
The phrase “Guidelines about how to configure…” can be made more direct. This small tweak improves flow and consistency with the other cards.

- Guidelines about how to configure popular MCP servers that can connect
- to both PostgreSQL and CrateDB.
+ Guidelines for configuring popular MCP servers that connect
+ to both PostgreSQL and CrateDB.
📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1d3527e and 7fae27d.

📒 Files selected for processing (4)
  • docs/integrate/index.md (1 hunks)
  • docs/integrate/mcp/community.md (1 hunks)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
  • docs/integrate/mcp/index.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
  • docs/integrate/index.md
  • docs/integrate/mcp/cratedb-mcp.md
  • docs/integrate/mcp/index.md
🧰 Additional context used
🧠 Learnings (1)
docs/integrate/mcp/community.md (2)
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.660Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.369Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mcp/community.md

37-37: Bare URL used
null

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms (1)
  • GitHub Check: Build docs
🔇 Additional comments (3)
docs/integrate/mcp/community.md (3)

1-5: Section introduction is clear and concise
The H1 title and introductory lines accurately describe the purpose of this document and fit seamlessly into the MCP integration guide.


36-43: Bare URL inside Sphinx directive is acceptable
Line 37 shows a bare URL in the :link: field. Although markdown lint flagged MD034, this is valid syntax within a Sphinx grid-item-card directive and will render correctly.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

37-37: Bare URL used
null

(MD034, no-bare-urls)


45-46: Closing directive
The final :::: closing tag correctly ends the grid container. No changes needed here.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7fae27d and 563017b.

📒 Files selected for processing (4)
  • docs/integrate/index.md (1 hunks)
  • docs/integrate/mcp/community.md (1 hunks)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
  • docs/integrate/mcp/index.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
  • docs/integrate/index.md
  • docs/integrate/mcp/index.md
🧰 Additional context used
🧠 Learnings (1)
docs/integrate/mcp/community.md (3)
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:8-20
Timestamp: 2025-05-18T12:50:38.660Z
Learning: In the CrateDB guide repository, references with the `ctk:` prefix (like `ctk:query/mcp/landscape`) are intersphinx references that link to resources in the cratedb-toolkit repository (https://github.com/crate/cratedb-toolkit/tree/main/doc), which are rendered at https://cratedb-toolkit.readthedocs.io/. These are valid cross-references between separate Sphinx documentation sets, not local file references.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:22-33
Timestamp: 2025-05-18T12:50:36.369Z
Learning: In the CrateDB Guide repository, the prefix `ctk:` in documentation links (like `ctk:query/mcp/server`) is an intersphinx reference that points to external content in the CrateDB Toolkit documentation at https://cratedb-toolkit.readthedocs.io/. These references are intentionally not pointing to local files within the repository.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/community.md:6-8
Timestamp: 2025-05-18T13:25:11.763Z
Learning: In the CrateDB Guide documentation, particularly for MCP-related pages, the author prefers a 1-column grid layout for multiple cards to stack them vertically rather than side by side, as this is an intentional design choice.
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mcp/community.md

36-36: Bare URL used
null

(MD034, no-bare-urls)

docs/integrate/mcp/cratedb-mcp.md

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms (1)
  • GitHub Check: Build docs
🔇 Additional comments (10)
docs/integrate/mcp/community.md (6)

1-5: Well-structured introduction section
The title and introductory text clearly communicate the purpose of the MCP Community Servers page, following existing documentation patterns.


6-8: Grid layout intentional
A single-column grid with a gutter of 2 is correctly configured, matching the repository’s design choice for vertical stacking of cards.


9-20: Valid intersphinx reference for MCP Server landscape
The ctk:query/mcp/landscape link correctly points to the external MCP landscape docs in the CrateDB Toolkit repository.


22-33: Valid intersphinx reference for MCP Server configuration
The second card’s ctk:query/mcp/server link properly targets the external configuration guide.


35-43: External examples URL usage
Embedding the GitHub URL within the :link: directive is appropriate for linking to external resources.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

36-36: Bare URL used
null

(MD034, no-bare-urls)


44-45: Proper closing of grid directive
The :::: closure correctly ends the grid layout directive.

docs/integrate/mcp/cratedb-mcp.md (4)

1-2: Clear page title
The H1 heading succinctly introduces the CrateDB MCP Server, consistent with other integration pages.


23-55: Grid layout and cards configuration
The grid directive (::::{grid} 1 2 2 2 with a gutter of 2) and its contained grid-item-card entries for the Python package, usage README, and examples are well-formed and consistent with the CrateDB Guide’s style.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)


57-63: Experimental caution admonition
The caution block clearly warns users that the MCP Server is experimental and is formatted according to repository conventions.


65-65: Reference link definition
The [MCP] reference link is correctly defined at the end of the file, pointing to the official MCP protocol site.

:class-footer: text-smaller

Guidelines for configuring popular MCP servers that connect
to both PostgreSQL and CrateDB.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: is it needed to mention postgresql?

Copy link
Member Author

@amotl amotl May 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi. I think it conveys best what's inside to make the reader expect the right thing: All of those community MCP database adapters are focusing on PostgreSQL, but work with CrateDB because it is compatible. 1

Do you see any harm in making the fact transparent that CrateDB is reasonably compatible with PostgreSQL, in this or other contexts? 1

Footnotes

  1. Sometimes it's only partially compatible, for example where it is not. However, I didn't want to get into that kind of rabbit hole here. ;] 2

[MCP], the Model Context Protocol, is an open protocol that enables seamless
integration between LLM applications and external data sources and tools.

Others define MCP as "It's effectively just OpenAPI for LLMs" or "It's the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Don't know if the sentence 'It's effectively just OpenAPI for LLMs' is relevant or makes sense

Copy link
Member Author

@amotl amotl May 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi, and thanks. This sloppy explanation has been picked up from discussions on the Web: It pretty much compresses the gist of the technology in a way to make it clear for decades of web developer's experiences what's actually inside.

Do you think the sentence has no value in this regard, is wrong, or do you think we should just phrase it less sloppy?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that the "effectively just" jargon would be flagged by prose linters as belittling. It's true, let's cut that away.

Copy link
Member Author

@amotl amotl May 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've compressed the statement per 717effd and hope it reads more pleasant now.

MCP is sometimes described as "OpenAPI for LLMs" or as "USB-C port for AI",
providing a uniform way to connect LLMs to resources they can use.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like some people are not just seeing the relationship, but actually started bridging the gap.

This repository provides reference OpenAPI Tool Server implementations making it easy and secure for developers to integrate external tooling and data sources into LLM agents and workflows. Designed for maximum ease of use and minimal learning curve, these implementations utilize the widely adopted and battle-tested OpenAPI specification as the standard protocol.

By leveraging OpenAPI, we eliminate the need for a proprietary or unfamiliar communication protocol, ensuring you can quickly and confidently build or integrate servers. This means less time spent figuring out custom interfaces and more time building powerful tools that enhance your AI applications.

-- https://github.com/open-webui/openapi-servers
-- https://docs.openwebui.com/openapi-servers/mcp#%EF%B8%8F-why-is-the-mcp-to-openapi-proxy-superior

It doesn't sound too bad, and it's not a one-way street.

For the easiest way to expose your MCP tools as OpenAPI-compatible APIs, we recommend using mcpo.

It is also possible to go the other direction: expose your OpenAPI-compatible tool server as an MCP server. This makes it easy to integrate any OpenAPI tool into environments or agents that expect an MCP-compatible interface.

Copy link
Contributor

@surister surister left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM


::::


Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add an "Example" section here, including a screenshot? Thanks, @hammerhead!

image

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added per 88c4cb5, thanks again.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
docs/integrate/mcp/cratedb-mcp.md (1)

26-54: Resource grid layout
The grid directive cleanly organizes the package link, usage guide, and examples. Note: markdownlint flags bare URLs (MD034) on the :link: lines—these are intentional within MyST directives and can be safely ignored or suppressed with <!-- markdownlint-disable MD034 --> if required.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 563017b and 88c4cb5.

📒 Files selected for processing (1)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
🧰 Additional context used
🧠 Learnings (1)
docs/integrate/mcp/cratedb-mcp.md (3)
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:3-8
Timestamp: 2025-05-18T13:39:58.358Z
Learning: In MyST Markdown, the correct syntax for rubric directives in the CrateDB documentation is:
```
:::{rubric} Title
:::
```
followed by the content outside of the directive. This is different from other admonition blocks where content is typically wrapped inside the directive.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:12-21
Timestamp: 2025-05-18T13:39:51.994Z
Learning: In MyST Markdown, the correct syntax for rubric directives is to close the directive immediately after the title, rather than wrapping the content:
```
:::{rubric} Title
:::

Content goes here (outside the directive)
```
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:3-8
Timestamp: 2025-05-18T13:39:58.358Z
Learning: In MyST Markdown, the rubric directive is used for informal headings and doesn't wrap content. The correct syntax is:
```
:::{rubric} Title
:::
```
followed by the content outside of the directive. This differs from admonition blocks which do wrap their content.
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mcp/cratedb-mcp.md

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)

🪛 GitHub Actions: docs
docs/integrate/mcp/cratedb-mcp.md

[warning] 57-57: 'rubric': Has content, but none permitted

🔇 Additional comments (9)
docs/integrate/mcp/cratedb-mcp.md (9)

1-2: Title Clarity and Placement
The document title accurately reflects the content and is correctly placed at the top of the page.


3-4: Correct use of rubric directive for "About"
The About section is immediately closed after the title, adhering to the MyST rubric syntax.


6-11: Concise overview in the "About" section
This text clearly summarizes the CrateDB MCP Server’s purpose and introduces the MCP protocol effectively.


12-13: Correct use of rubric directive for "Introduction"
The Introduction rubric is closed immediately after the title, matching the expected MyST pattern.


15-21: Clear and informative introduction
These lines effectively explain how the MCP Server bridges AI assistants and CrateDB clusters using natural language.


23-24: Correct rubric usage for "What's inside"
The "What's inside" section is properly annotated as a rubric with an immediate closing.


59-64: Example conversation clarity
The sample dialog and accompanying screenshot effectively demonstrate real-world usage.


66-72: Proper use of caution directive
The caution block clearly warns about the experimental status and is formatted correctly.


74-75: Verify MCP protocol link
Ensure that the reference URL for the MCP specification is current and correct.

Please confirm that https://modelcontextprotocol.io/ is the authoritative endpoint for the MCP documentation.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

🧹 Nitpick comments (2)
docs/integrate/mcp/cratedb-mcp.md (2)

23-24: Consistent rubric directive for "What's inside" section.
Consider capitalizing "Inside" for title-case consistency.

Apply this diff:

-:::{rubric} What's inside
+:::{rubric} What's Inside

60-64: Enhance image accessibility with descriptive alt text.
The current alt text "image" is generic. Consider a more meaningful description.

Apply this diff:

-![image](https://github.com/user-attachments/assets/db127717-329a-4d0e-901c-3e3dcaefefb9)
+![Example MCP conversation screenshot](https://github.com/user-attachments/assets/db127717-329a-4d0e-901c-3e3dcaefefb9)
📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 88c4cb5 and 8fe3bd9.

📒 Files selected for processing (1)
  • docs/integrate/mcp/cratedb-mcp.md (1 hunks)
🧰 Additional context used
🧠 Learnings (1)
docs/integrate/mcp/cratedb-mcp.md (3)
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:3-8
Timestamp: 2025-05-18T13:39:58.358Z
Learning: In MyST Markdown, the correct syntax for rubric directives in the CrateDB documentation is:
```
:::{rubric} Title
:::
```
followed by the content outside of the directive. This is different from other admonition blocks where content is typically wrapped inside the directive.
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:12-21
Timestamp: 2025-05-18T13:39:51.994Z
Learning: In MyST Markdown, the correct syntax for rubric directives is to close the directive immediately after the title, rather than wrapping the content:
```
:::{rubric} Title
:::

Content goes here (outside the directive)
```
Learnt from: amotl
PR: crate/cratedb-guide#204
File: docs/integrate/mcp/cratedb-mcp.md:3-8
Timestamp: 2025-05-18T13:39:58.358Z
Learning: In MyST Markdown, the rubric directive is used for informal headings and doesn't wrap content. The correct syntax is:
```
:::{rubric} Title
:::
```
followed by the content outside of the directive. This differs from admonition blocks which do wrap their content.
🪛 markdownlint-cli2 (0.17.2)
docs/integrate/mcp/cratedb-mcp.md

30-30: Bare URL used
null

(MD034, no-bare-urls)


39-39: Bare URL used
null

(MD034, no-bare-urls)


47-47: Bare URL used
null

(MD034, no-bare-urls)

⏰ Context from checks skipped due to timeout of 90000ms (1)
  • GitHub Check: Build docs
🔇 Additional comments (12)
docs/integrate/mcp/cratedb-mcp.md (12)

3-4: Correct usage of rubric directive for "About" section.
The :::{rubric} About block is opened and closed immediately according to MyST syntax.


6-8: Clear description of the CrateDB MCP Server.
The overview succinctly explains the server’s purpose and specialization.


9-11: Accurate introduction of the MCP protocol.
You correctly link the acronym to its definition for clarity.


12-13: Correct usage of rubric directive for "Introduction" section.
The rubric is properly opened and closed immediately per MyST conventions.


15-21: Well-structured introduction content.
The text clearly outlines the MCP Server’s role and capabilities.


26-36: Grid layout for resources is well-defined.
The first grid-item-card cleanly links to the Python package.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

30-30: Bare URL used
null

(MD034, no-bare-urls)


38-45: Usage link card is clear and concise.
The Usage card correctly points to the README with appropriate metadata.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

39-39: Bare URL used
null

(MD034, no-bare-urls)


46-53: Examples card is informative.
The description and link to the examples repository are accurate.

🧰 Tools
🪛 markdownlint-cli2 (0.17.2)

47-47: Bare URL used
null

(MD034, no-bare-urls)


54-55: Proper closure of the grid directive.
The :::: closing tag matches the opening ::::{grid}.


57-58: Correct usage of rubric directive for "Example" section.
The rubric block follows syntax conventions and is immediately closed.


67-73: Caution admonition correctly formatted.
The experimental notice is properly fenced and clearly communicated.


75-75: Reference link for MCP protocol is present.
The [MCP] footnote correctly points to the official protocol website.

@amotl amotl merged commit 65c16fb into main May 20, 2025
3 checks passed
@amotl amotl deleted the mcp-first branch May 20, 2025 01:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants