From cbfd84f696425f073693d8e7f4ee0da86d4ed2ec Mon Sep 17 00:00:00 2001 From: dtehan-td Date: Thu, 2 Oct 2025 12:24:38 -0700 Subject: [PATCH] Documentation Simplification & navigation --- README.md | 70 +-------------------- docs/README.md | 6 +- docs/client_guide/CLIENT_GUIDE.md | 3 + docs/client_guide/MCP_Inspector.md | 19 +++++- docs/developer_guide/DEVELOPER_GUIDE.md | 2 + docs/server_guide/ARCHITECTURE.md | 3 +- docs/server_guide/CONFIGURATION.md | 2 +- docs/server_guide/CUSTOMIZING.md | 3 +- docs/server_guide/GETTING_STARTED.md | 18 +----- docs/server_guide/INSTALLATION.md | 2 +- docs/server_guide/QUICK_START.md | 2 +- docs/server_guide/QUICK_START_OPEN_WEBUI.md | 2 +- docs/server_guide/QUICK_START_VSCODE.md | 4 +- docs/server_guide/SECURITY.md | 2 +- docs/server_guide/VIDEO_LIBRARY.md | 4 ++ examples/README.md | 2 + 16 files changed, 47 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 579f4f3..45b2b9f 100644 --- a/README.md +++ b/README.md @@ -80,87 +80,23 @@ Configure the claude_desktop_config.json (Settings>Developer>Edit Config) by add } ``` -## Setting up your environment +## Installation Instructions Follow this process to install your server, connect it to your Teradata platform and integrated your tools. **Step 1.** - Identify the running Teradata System, you need username, password and host details. If you do not have a Teradata system to connect to, then leverage [Teradata Clearscape Experience](https://www.teradata.com/getting-started/demos/clearscape-analytics) -**Step 2.** - To install, configure and run the MCP server, refer to the [Getting started guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/server_guide/GETTING_STARTED.md), or see below for a quick [CLI installation](#CLI-Installation). You can easily [customize the server with your own tools, prompts and resources](docs/server_guide/CUSTOMIZING.md). +**Step 2.** - To install, configure and run the MCP server, refer to the [Teradata MCP Server Documentation](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/README.md). **Step 3.** - There are many client options available, the [Client Guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/README.md#-client-guide) explains how to configure and run a sample of different clients.
-Check out our [documentation](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/README.md) and libraries of [curated examples](https://github.com/Teradata/teradata-mcp-server/blob/main/examples/) or [video guides](https://github.com/Teradata/teradata-mcp-server/blob/doc-v1.4/docs/server_guide/VIDEO_LIBRARY.md). +Check out our libraries of [curated examples](https://github.com/Teradata/teradata-mcp-server/blob/main/examples/) or [video guides](https://github.com/Teradata/teradata-mcp-server/blob/doc-v1.4/docs/server_guide/VIDEO_LIBRARY.md).
-## CLI Installation -We recommend `uv` or `pipx` to install teradata-mcp-server as a CLI tool on your system. -They provide isolated environments and ensure the `teradata-mcp-server` command is available system-wide without interfering with system Python. - -```bash -uv tool install "teradata-mcp-server" -``` - -or with pipx - -```bash -pipx install "teradata-mcp-server" -``` - -To install the optional Enterprise Feature Store (fs) and Enterprise Vector Store (evs) packages: -```bash -uv tool install "teradata-mcp-server[fs,evs]" -``` - -Alternatively, you may use pip in a virtual environment (Python>=3.11): - -```bash -pip install teradata-mcp-server -``` - -For usage: - -```bash -teradata-mcp-server --help -``` - -**Troubleshooting** -When using uv, If the tool's path isn't resolved add it to your shell using `uv tool update-shell` and restart the terminal. - -## Build from Source (Development) - -For development or customization, you can build from source: - -1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/). If you are on macOS, use Homebrew: `brew install uv` -2. Clone this repository: `git clone https://github.com/Teradata/teradata-mcp-server.git` -3. Navigate to the directory: `cd teradata-mcp-server` -4. Run the server: `uv run teradata-mcp-server` - -For Claude Desktop with development build, use this configuration: - -```json -{ - "mcpServers": { - "teradata": { - "command": "uv", - "args": [ - "--directory", - "/teradata-mcp-server", - "run", - "teradata-mcp-server" - ], - "env": { - "DATABASE_URI": "teradata://:@:1025/", - "MCP_TRANSPORT": "stdio" - } - } - } -} -``` ## Contributing Please refer to the [Contributing](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/developer_guide/CONTRIBUTING.md) guide and the [Developer Guide](https://github.com/Teradata/teradata-mcp-server/blob/main/docs/developer_guide/DEVELOPER_GUIDE.md). diff --git a/docs/README.md b/docs/README.md index bd05303..3c8f0a5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,5 +1,7 @@ # Teradata MCP Server Documentation +> **πŸ“ Navigation:** [Documentation Home](../README.md) | **Server Guide** + This guide will help you get started, configure, and customize your Teradata MCP Server setup. ## πŸš€ Quick Start @@ -23,15 +25,13 @@ New to Teradata MCP Server? Choose your 5-minute quickstart to rapidly evaluate Everything you need to know about running and configuring the MCP server: - **[Getting Started](server_guide/GETTING_STARTED.md)** - Choose your path (routing guide) -- **[Quick Start (Claude)](server_guide/QUICK_START.md)** - 5-minute Claude Desktop setup using `stdio` transport mode -- **[Quick Start (VS Code + Copilot)](server_guide/QUICK_START_VSCODE.md)** - 5-minute VS Code and GitHub Copilot setup using `streamable-http` transport mode -- **[Quick Start (Open WebUI)](server_guide/QUICK_START_OPEN_WEBUI.md)** - 5-minute Open WebUI setup using REST interface - **[Installation](server_guide/INSTALLATION.md)** - Deployment methods and options - **[Configuration](server_guide/CONFIGURATION.md)** - Server settings and tuning - **[Architecture](server_guide/ARCHITECTURE.md)** - How components work together - **[Customizing](server_guide/CUSTOMIZING.md)** - Add your own tools and business logic - **[Security](server_guide/SECURITY.md)** - Authentication and access control + ### πŸ‘₯ Client Guide Connect different AI clients to your Teradata MCP Server: diff --git a/docs/client_guide/CLIENT_GUIDE.md b/docs/client_guide/CLIENT_GUIDE.md index 634be97..6ef5d59 100644 --- a/docs/client_guide/CLIENT_GUIDE.md +++ b/docs/client_guide/CLIENT_GUIDE.md @@ -1,5 +1,7 @@ # Working with MCP Clients +> **πŸ“ Navigation:** [Documentation Home](../README.md) | **Client Guide** + ![Getting Started](../media/MCP-quickstart.png) This documet will cover the process and options for getting a client tool to connect to the teradata-mcp-server. Note that you have many client options, we will cover some but not all. @@ -19,6 +21,7 @@ There are many client options that you can choose from, they each have different - [Google AgentSpace](./Google_agentspace.md) - [Open WebUI](./Open_WebUI.md) - [teradata-trusted-data-agent](https://github.com/rgeissen/teradata-trusted-data-agent) +- [Perplexity Desktop](Perplexity%20Desktop.md) ## Audio Client - [MCP Voice Client](../../examples/MCP_VoiceClient/README.md) diff --git a/docs/client_guide/MCP_Inspector.md b/docs/client_guide/MCP_Inspector.md index 8ef098a..7aaa554 100644 --- a/docs/client_guide/MCP_Inspector.md +++ b/docs/client_guide/MCP_Inspector.md @@ -9,8 +9,25 @@ uv run src/teradata_mcp_server ``` Step 1 - In a second terminal start the inspector, type the following in your terminal +The [MCP inspector](https://www.npmjs.com/package/@modelcontextprotocol/inspector/v/0.9.0) provides you with a convenient way to browse and test tools, resources and prompts: + +You can use the inspector to directly run the MCP server and connect over stdio: + +**Using the development environment:** +```bash + npx modelcontextprotocol/inspector uv run teradata-mcp-server +``` + +**Using the installed package:** +```bash + npx modelcontextprotocol/inspector teradata-mcp-server ``` -uv run mcp dev ./src/teradata_mcp_server/server.py + +You may also run the MCP server as a separate process and connect to it form the inspector over http: + +```bash +uv run teradata-mcp-server --mcp_transport streamable-http +npx modelcontextprotocol/inspector ``` NOTE: If you are running this on a Windows machine and get npx, npm or node.js errors, install the required node.js software from here: https://github.com/nodists/nodist diff --git a/docs/developer_guide/DEVELOPER_GUIDE.md b/docs/developer_guide/DEVELOPER_GUIDE.md index 35b059c..3edc6c8 100644 --- a/docs/developer_guide/DEVELOPER_GUIDE.md +++ b/docs/developer_guide/DEVELOPER_GUIDE.md @@ -1,5 +1,7 @@ # Development Conventions +> **πŸ“ Navigation:** [Documentation Home](../README.md) | **Developer Guide** + This document provides guidelines for developing new tools for the Teradata MCP server.
diff --git a/docs/server_guide/ARCHITECTURE.md b/docs/server_guide/ARCHITECTURE.md index 4b6e1ab..2b272fd 100644 --- a/docs/server_guide/ARCHITECTURE.md +++ b/docs/server_guide/ARCHITECTURE.md @@ -1,6 +1,7 @@ # Architecture Overview -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | **Architecture** | [Quick Start](QUICK_START.md) | [Installation](INSTALLATION.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting started](GETTING_STARTED.md) | [**Architecture**](ARCHITECTURE.md) | [Installation](INSTALLATION.md) | [Configuration](CONFIGURATION.md) | [Security](SECURITY.md) | [Customization](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) + > **🎯 Goal:** Understand how Teradata MCP Server components work together diff --git a/docs/server_guide/CONFIGURATION.md b/docs/server_guide/CONFIGURATION.md index 06d9be1..84cdf2c 100644 --- a/docs/server_guide/CONFIGURATION.md +++ b/docs/server_guide/CONFIGURATION.md @@ -1,6 +1,6 @@ # Server Configuration -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Quick Start](QUICK_START.md) | [Installation](INSTALLATION.md) | **Configuration** +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting started](GETTING_STARTED.md) | [Architecture](ARCHITECTURE.md) | [Installation](INSTALLATION.md) | [**Configuration**](CONFIGURATION.md) | [Security](SECURITY.md) | [Customization](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) > **🎯 Goal:** Configure your MCP server for optimal performance and security diff --git a/docs/server_guide/CUSTOMIZING.md b/docs/server_guide/CUSTOMIZING.md index 16d90ac..19d8594 100644 --- a/docs/server_guide/CUSTOMIZING.md +++ b/docs/server_guide/CUSTOMIZING.md @@ -1,7 +1,8 @@ # Customizing the MCP Server: Semantic Layers -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting Started](GETTING_STARTED.md) | **Customizing** | [Security](SECURITY.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting started](GETTING_STARTED.md) | [Architecture](ARCHITECTURE.md) | [Installation](INSTALLATION.md) | [Configuration](CONFIGURATION.md) | [Security](SECURITY.md) | [**Customization**](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) + The Teradata MCP server enables rapid creation of domain-focused semantic layers by allowing you to declaratively define custom tools, prompts, cubes, and glossary terms. No code change needed, you can customize the server by placing YAML files in your current working directory. This approach empowers admins and data teams to tailor the MCP experience to specific business domainsβ€”without writing Python code or modifying the server itself. diff --git a/docs/server_guide/GETTING_STARTED.md b/docs/server_guide/GETTING_STARTED.md index 9e0edb6..babcf1c 100644 --- a/docs/server_guide/GETTING_STARTED.md +++ b/docs/server_guide/GETTING_STARTED.md @@ -1,25 +1,9 @@ # Getting Started with Teradata MCP Server -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | **Getting Started** | [Customizing](CUSTOMIZING.md) | [Security](SECURITY.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [**Getting started**](GETTING_STARTED.md) | [Architecture](ARCHITECTURE.md) | [Installation](INSTALLATION.md) | [Configuration](CONFIGURATION.md) | [Security](SECURITY.md) | [Customization](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) Welcome to the Teradata MCP Server! This guide helps you choose the right starting point based on your needs. -## 🎯 What Do You Want To Do? - -### πŸš€ **Just Want to Try It? (5 minutes)** - -New to Teradata MCP Server? Choose your 5-minute quickstart to rapidly evaluate the server with your favorite tool: - -| **Client** | **Deployment** | **Communication** | **Best For** | -|------------|----------------|------------------|--------------| -| [Claude Desktop](./QUICK_START.md) | CLI (uv/pipx) | stdio | Exploratory Data Analytics, Platform Administration, general evaluation | -| [VS Code + Copilot](./QUICK_START_VSCODE.md) | CLI (uv/pipx) | HTTP | Data Engineering, Agentic app development | -| [Open WebUI](./QUICK_START_OPEN_WEBUI.md) | Docker | REST | Local AI, evaluate new LLMs | -| [Code examples](../examples/README.md) | Python | HTTP | Build your own client. Example library using ADK, Bedrock, Langchain... | - -*All options get you running in 5 minutes with minimal configuration.* - ---- ### πŸ— **Setting Up your environment? (15 minutes)** **β†’ [Installation Guide](INSTALLATION.md)** diff --git a/docs/server_guide/INSTALLATION.md b/docs/server_guide/INSTALLATION.md index fe33fca..21e94c9 100644 --- a/docs/server_guide/INSTALLATION.md +++ b/docs/server_guide/INSTALLATION.md @@ -1,6 +1,6 @@ # Installation & Deployment Guide -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Quick Start](QUICK_START.md) | **Installation** | [Configuration](CONFIGURATION.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting started](GETTING_STARTED.md) | [Architecture](ARCHITECTURE.md) | [**Installation**](INSTALLATION.md) | [Configuration](CONFIGURATION.md) | [Security](SECURITY.md) | [Customization](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) > **🎯 Goal:** Choose and implement the best deployment method for your needs diff --git a/docs/server_guide/QUICK_START.md b/docs/server_guide/QUICK_START.md index bb39fec..e080a7a 100644 --- a/docs/server_guide/QUICK_START.md +++ b/docs/server_guide/QUICK_START.md @@ -1,6 +1,6 @@ # 5-Minute Quick Start with Claude -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | **Quick Start** | [Installation](INSTALLATION.md) | [Configuration](CONFIGURATION.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-quick-start) | **Quick Start Claude** | [Quick Start VS Code](QUICK_START_VSCODE.md) | [Quick Start Open WebUI](QUICK_START_OPEN_WEBUI.md) | [Code Examples](../../examples/README.md) > **🎯 Goal:** Get a working MCP server connected to Claude Desktop in 5 minutes diff --git a/docs/server_guide/QUICK_START_OPEN_WEBUI.md b/docs/server_guide/QUICK_START_OPEN_WEBUI.md index 2f654ac..b8ae08a 100644 --- a/docs/server_guide/QUICK_START_OPEN_WEBUI.md +++ b/docs/server_guide/QUICK_START_OPEN_WEBUI.md @@ -1,6 +1,6 @@ # 5-Minute Quick Start (Open WebUI) -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | **Quick Start Open WebUI** | [Quick Start Claude](QUICK_START.md) | [Quick Start VS Code](QUICK_START_VSCODE.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-quick-start) | [Quick Start Claude](QUICK_START.md) | [Quick Start VS Code](QUICK_START_VSCODE.md) | **Quick Start Open WebUI** | [Code Examples](../../examples/README.md) > **🎯 Goal:** Get a working MCP server connected to Open WebUI in 5 minutes diff --git a/docs/server_guide/QUICK_START_VSCODE.md b/docs/server_guide/QUICK_START_VSCODE.md index f08cc97..9da64c1 100644 --- a/docs/server_guide/QUICK_START_VSCODE.md +++ b/docs/server_guide/QUICK_START_VSCODE.md @@ -1,6 +1,6 @@ # 5-Minute Quick Start (Visual Studio Code with GitHub Copilot) -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | **Quick Start VS Code** | [Quick Start Claude](QUICK_START.md) | [Installation](INSTALLATION.md) +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-quick-start) | [Quick Start Claude](QUICK_START.md) | **Quick Start VS Code** | [Quick Start Open WebUI](QUICK_START_OPEN_WEBUI.md) | [Code Examples](../../examples/README.md) > **🎯 Goal:** Get a working MCP server connected to VS Code and GitHub Copilot in 5 minutes @@ -63,7 +63,7 @@ Add MCP Server via Command Palette: You should see a configuration as follows in your mcp.json file: -![alt text](media/vscode-mcp-json.png) +![alt text](../media/vscode-mcp-json.png) ## ✨ Step 4: Test It (30 seconds) diff --git a/docs/server_guide/SECURITY.md b/docs/server_guide/SECURITY.md index b9e8f74..84d545e 100644 --- a/docs/server_guide/SECURITY.md +++ b/docs/server_guide/SECURITY.md @@ -1,6 +1,6 @@ # Security Configuration -> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting Started](GETTING_STARTED.md) | [Customizing](CUSTOMIZING.md) | **Security** +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-server-guide) | [Getting started](GETTING_STARTED.md) | [Architecture](ARCHITECTURE.md) | [Installation](INSTALLATION.md) | [Configuration](CONFIGURATION.md) | [**Security**](SECURITY.md) | [Customization](CUSTOMIZING.md) | [Client Guide](../client_guide/CLIENT_GUIDE.md) All database tool calls are traced using [Teradata DBQL](https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/Database-Administration/Tracking-Query-Behavior-with-Database-Query-Logging-Operational-DBAs), and the MCP server implements query banding by default. diff --git a/docs/server_guide/VIDEO_LIBRARY.md b/docs/server_guide/VIDEO_LIBRARY.md index 0a79592..925bd6d 100644 --- a/docs/server_guide/VIDEO_LIBRARY.md +++ b/docs/server_guide/VIDEO_LIBRARY.md @@ -1,5 +1,9 @@ + # Video Library +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md) | **Video Library** + + The video library is a curation of videos that the community believes would be valuable for new members. ## Demo's diff --git a/examples/README.md b/examples/README.md index c7e6504..53c4b50 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,5 +1,7 @@ # Examples +> **πŸ“ Navigation:** [Documentation Home](../README.md) | [Server Guide](../README.md#-quick-start) | [Quick Start Claude](../docs/server_guide/QUICK_START.md) | [Quick Start VS Code](../docs/server_guide/QUICK_START_VSCODE.md) | [Quick Start Open WebUI](../docs/server_guide/QUICK_START_OPEN_WEBUI.md) | **Code Examples** + This directory contains application examples and configurations for the Teradata MCP Server. These examples demonstrate different ways to customize, configure, and build upon the server. ## Server Customization