@sassoftware/sas-score-mcp-serverjs 0.0.2

package/QUICK_REFERENCE.md

@@ -0,0 +1,378 @@
+# Tool Description Template - Quick Reference
+
+## The 9 Essential Sections
+
+Every tool description should follow this exact structure:
+
+### 1️⃣ **Title Line**
+```markdown
+## toolName — brief one-liner description
+```
+- Clear, action-oriented
+- Include purpose/benefit
+- Use em dash (—) not colon
+
+### 2️⃣ **LLM Invocation Guidance (When to use)**
+```markdown
+Use THIS tool when:
+- "example user request 1"
+- "example user request 2"
+- "example user request 3"
+```
+- Explicit: "Use THIS tool when..."
+- Real user phrases with quotes
+- 3-5 examples
+- Show actual language patterns
+
+### 3️⃣ **Do NOT use this tool for:**
+```markdown
+- What NOT to do (use toolX instead)
+- Another misuse case (use toolY instead)
+- Common misconception (use toolZ instead)
+```
+- List what NOT to do
+- Always specify alternative tool
+- Prevent tool misuse
+
+### 4️⃣ **Purpose**
+```markdown
+Clear explanation of what this tool does.
+1-3 sentences maximum.
+Explain the business value, not just mechanics.
+```
+- Concise (1-3 sentences)
+- Focus on "why" not just "what"
+- Explain when/why someone uses it
+
+### 5️⃣ **Parameters**
+```markdown
+- paramName (type, default): Description of what this parameter does.
+- anotherParam (type, required): Description explaining constraints.
+```
+- Every parameter documented
+- Format: `name (type, default): description`
+- Include constraints: `(1-100)`, `(required)`, `(optional)`
+- Add examples of valid values
+
+### 6️⃣ **Response Contract**
+```markdown
+Returns a JSON object containing:
+- fieldName: Description of what this field contains
+- otherField: Type and description
+- Empty array if no results
+- Error cases and how they're represented
+```
+- Describe JSON structure
+- List key fields and types
+- Cover edge cases (empty, null, errors)
+- Example response helpful
+
+### 7️⃣ **Disambiguation & Clarification**
+```markdown
+- If user says "X" without specifying Y: ask "Did you mean Z?"
+- If parameter is missing: ask "Which [param] would you like?"
+- Handle multiple requests: clarify which one
+```
+- Format: `- If user says "X" → ask "[question]"`
+- Exact questions to ask (in quotes)
+- Edge cases and confusion points
+
+### 8️⃣ **Examples (→ mapped params)**
+```markdown
+- "user phrase example 1" → { param: "value", limit: 10 }
+- "another user request" → { param: "value" }
+- "with different params" → { param1: "x", param2: "y" }
+```
+- Real user phrases (with quotes)
+- Arrow notation: `→`
+- Show parameter mappings
+- 3-5 examples covering different scenarios
+
+### 9️⃣ **Negative Examples (should NOT call toolName)**
+```markdown
+- "incorrect user request" (use toolX instead)
+- "another common mistake" (use toolY instead)
+```
+- Show what NOT to do
+- Always specify correct tool
+- 2-3 examples of common mistakes
+
+### 🔟 **Related Tools** (optional but recommended)
+```markdown
+- listThing → findThing → infoThing → actionThing (typical workflow)
+- otherTool — description of how it relates
+```
+- Show workflow chains
+- Show prerequisites
+- Show follow-up tools
+
+---
+
+## Formatting Checklist
+
+- [ ] Use `## title` for main header
+- [ ] Use `###` or bold for section headers
+- [ ] Use `- ` for bullet points
+- [ ] Use `` `code` `` for parameter/field names
+- [ ] Use quotes `"..."` for example user phrases
+- [ ] Use em dash `→` in examples (not arrow)
+- [ ] Use em dash `—` in title (not colon or dash)
+- [ ] Consistent indentation
+- [ ] No typos (spell-check parameter names)
+
+---
+
+## Parameter Documentation Format
+
+**Minimal:**
+```
+- name (string): Description.
+```
+
+**With defaults:**
+```
+- name (string, default 'value'): Description.
+```
+
+**With constraints:**
+```
+- name (number, 1-100, default 10): Description.
+```
+
+**Optional parameter:**
+```
+- name (string, optional): Description.
+```
+
+**Required parameter:**
+```
+- name (string, required): Description.
+```
+
+---
+
+## Example Parameter Variations
+
+```markdown
+Parameters
+- model (string, required): The name of the model to analyze.
+- limit (number, default 10): Maximum results (1-1000).
+- where (string, optional): SQL-style filter clause.
+- server (string, default 'cas'): Target server: 'cas' or 'sas'.
+- format (boolean, default true): Return formatted values when true.
+```
+
+---
+
+## Response Contract Examples
+
+### Simple (scalar return)
+```markdown
+Response Contract
+Returns a JSON object with:
+- result: The computed numeric value (number)
+```
+
+### Array return
+```markdown
+Response Contract
+Returns an array of objects:
+- Each object contains { name: string, value: any }
+- Empty array if no results found
+```
+
+### Complex structure
+```markdown
+Response Contract
+Returns a JSON object with:
+- models: Array of model objects containing:
+  - name: Model name (string)
+  - type: Model type (string)
+  - metadata: Optional model metadata (object)
+- count: Total number of models (number)
+- pageInfo: Pagination information if applicable
+```
+
+---
+
+## Example vs Negative Example Format
+
+**Examples format:**
+```
+- "read 10 rows from customers" → { table: "customers", limit: 10 }
+- "get all columns from orders" → { table: "orders" }
+```
+
+**Negative Examples format:**
+```
+- "execute this SQL query" (use sasQuery instead)
+- "run this SAS program" (use program instead)
+```
+
+---
+
+## Common Mistakes to Avoid
+
+❌ **Bad: Vague description**
+```
+## listThings
+
+Provides a list of things.
+```
+
+✅ **Good: Clear description**
+```
+## listThings — enumerate available items with pagination support
+```
+
+---
+
+❌ **Bad: No usage guidance**
+```
+Parameters
+- name (string): The name
+```
+
+✅ **Good: Clear guidance**
+```
+Parameters
+- name (string, required): The exact name of the item to retrieve.
+  Names are case-sensitive. Examples: 'myItem', 'item_123'
+```
+
+---
+
+❌ **Bad: Abstract examples**
+```
+Examples
+- basic usage
+- advanced usage with parameters
+```
+
+✅ **Good: Real examples**
+```
+Examples (→ mapped params)
+- "list all models" → { start: 1, limit: 10 }
+- "show me 25 models" → { start: 1, limit: 25 }
+```
+
+---
+
+❌ **Bad: Missing related tools**
+```
+[Description ends]
+```
+
+✅ **Good: Context**
+```
+Related Tools
+- listModels → findModel → modelInfo → modelScore (typical workflow)
+- findModel — to check if a specific model exists
+- modelScore — to score using this model
+```
+
+---
+
+## Section Order (IMPORTANT)
+
+Always use this exact order:
+1. Title
+2. LLM Invocation Guidance (When to use)
+3. Do NOT use this tool for
+4. Purpose
+5. Parameters
+6. Response Contract
+7. Disambiguation & Clarification
+8. Examples (→ mapped params)
+9. Negative Examples
+10. Related Tools (optional)
+
+---
+
+## Line Length Guidelines
+
+- Keep lines under 100 characters for readability
+- Parameter descriptions can wrap across 2-3 lines
+- Real-world example lines can be longer if needed
+
+---
+
+## Testing Your Description
+
+Before submitting, verify:
+
+1. **Can an LLM understand when to use this?**
+   - Read the "LLM Invocation Guidance" section
+   - Does it have real user phrase examples?
+
+2. **Can an LLM understand what NOT to do?**
+   - Read the "Do NOT use" section
+   - Does it specify which tool to use instead?
+
+3. **Can an LLM invoke this correctly?**
+   - Look at the "Examples" section
+   - Are parameter mappings clear and realistic?
+
+4. **Does it match the template format?**
+   - Use the 9-section checklist above
+   - All required sections present?
+   - Proper markdown formatting?
+
+5. **Is it consistent with other tools?**
+   - Same structure as similar tools?
+   - Same tone and style?
+   - Same level of detail?
+
+---
+
+## Quick Copy-Paste Template
+
+```markdown
+## toolName — brief one-liner
+
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- "example 1"
+- "example 2"
+- "example 3"
+
+Do NOT use this tool for:
+- Wrong use case (use toolX instead)
+- Another wrong case (use toolY instead)
+
+Purpose
+[1-3 sentences explaining what this tool does]
+
+Parameters
+- param1 (type, default): Description
+- param2 (type, required): Description
+
+Response Contract
+[Describe JSON response structure]
+
+Disambiguation & Clarification
+- If user says "X" → ask "question?"
+- If missing param → ask "which param?"
+
+Examples (→ mapped params)
+- "user request 1" → { param1: "value" }
+- "user request 2" → { param1: "value", param2: 10 }
+
+Negative Examples (should NOT call toolName)
+- "wrong request" (use toolX instead)
+- "another mistake" (use toolY instead)
+
+Related Tools
+- toolX — description
+- toolY — description
+```
+
+---
+
+## Questions?
+
+Refer to:
+- `TOOL_DESCRIPTION_TEMPLATE.md` - Detailed specification
+- `EXAMPLE_IMPROVEMENTS.md` - Before/after comparisons
+- `TOOL_UPDATES_SUMMARY.md` - What was updated
+- Updated tool files in `src/toolSet/` - Real examples

package/README.md

@@ -0,0 +1,267 @@
+# sas-score-mcp-serverjs
+A Model Context Protocol (MCP) Server for Scoring with SAS Viya
+
+## Overview
+This MCP server is designed for scoring with SAS Viya.
+
+> Note: **scoring** refers to executing any code that takes some input and returns results.
+
+Some examples are:
+
+- models created with SAS solutions like Model Studio, Intelligent Decisioning etc...
+- user written SAS program
+  - SAS Studio Flow
+  - job Definitions
+  - jobs using SAS Studio or other interfaces
+
+## Target Audience
+This MCP server was developed for two types of SAS users.
+
+### SAS users
+SAS users who want to use natural language("chat") to execute prebuilt SAS code and models.
+See this [quick reference](../sas-mcp-tools-reference.md) for details.
+
+### MCP tool developers 
+SAS developers who want to extend the capabilities of the server with their own tools. See the [guide](../tool-developer-guide.md) for details.
+
+## Configuration Variables
+Typically these are set either in the .env file or as environment variables (or both). This is full list of the configuration variables used the mcp server.
+
+```env
+
+# Indicate what type of transport(stdio|http)
+# http is useful for remote mcp servers
+# If running locally, recommend stdio
+
+MCPTYPE=http
+
+# Port for http transport(default is 8080)
+
+PORT=8080
+
+# If transport is http, optionally specify if the server
+# is using http or https
+
+HTTPS=FALSE
+
+
+# Viya Authentication
+# The mcp server support different ways to authenticate(see section on Authentication)
+
+# * sascli * will look for tokens created with sas-viya cli
+# * token * a custom token
+# * password * userid/password 
+
+AUTHFLOW=sascli
+SAS_CLI_CONFIG=your-home-directory
+SAS_CLI_PROFILE=your-sas-cli-profile
+
+# VIYA_SERVER URL for AUTHFLOW of token and password
+
+VIYA_SERVER= your Viya server url
+
+# if AUTHFLOW=token, specify the file with the token
+TOKENFILE=
+
+# if password flow specify these
+CLIENTIDPW=
+CLIENTSECRET=
+PASSWORD=
+
+# When HTTPS is TRUE, specify the folder with SSL certificates for the mcp server
+# All files in that folder will be loaded and used in the TLS connection
+# If not set and HTTPS is true, the server will create a self-signed certificate
+
+SSLCERT=<some folder>
+
+
+# This certificate isused in the http calls to SAS Viya from MCP server
+# Used in restaf (ultimately axios and fetch)
+# All files in the folder will be loaded and used in the TLS connection
+# if not set, no ssl certificates will be used
+# See the script in scripts/getViyaca.sh to get this certificate from the SAS Viya server
+
+VIYACERT=<some folder>
+
+# SAS Contexts
+# These are for the CAS and SAS sessions
+# Defaults are:
+COMPUTECONTEXT=SAS Job Execution compute context
+CASSERVER=cas-shared-default
+
+```
+
+## Authentication
+The server supports multiple ways to authenticate.
+
+### sas-viya cli
+
+> Note: To use this, set `AUTHFLOW=sascli`
+
+This MCP server CLI works similar to SAS supplied sas-viya CLI commands.
+Use the following command to create the necessary token and refresh token.
+
+`create a default auth Profile`.
+Issue this command and follow instruction: `sas-viya profile init`
+
+`create token`
+Issue this command and follow the instructions: `sas-viya auth loginCode`
+
+You need to do this once every 90 days or whenever the refresh token expires.
+
+At this point the tools can make authenticated calls to SAS Viya.
+
+### Password
+
+> Note: To use this, set `AUTHTYPE=password`
+
+Ths requires additional setup:
+
+- Create a clientid and client password for Oauth password flow.
+- Set these in the .env file or the mcp configuration file
+
+### Custom token
+
+> Note: To use this,  set `AUTHTYPE=token`
+
+Set the env TOKENFILE to a file containing the token.
+
+There seems to be a pattern of using a long-lived token.
+If this is your use case, set the TOKENFILE to a file containing this token.
+
+### Oauth
+This is under development.
+
+## Transport Methods
+This server supports both stdio and http transport methods.
+
+### stdio transport
+This is ideal for running mcp servers locally.
+Most clients will autostart the mcp server for you.
+
+> Note: You must set the MCPTYPE in the environment variable.
+
+```json
+  "sasmcp": {
+    "type": "stdio",
+    "command": "npx",
+    "args": [
+      "@sassoftware/sas-app-mcp-serverjs@latest",
+    ],
+    "env": {
+      "MCPTYPE": "stdio",
+      "AUTHFLOW": "sascli",  // sascli|password|token
+      "SAS_CLI_PROFILE": "cli profile name or Default",
+      "SAS_CLI_CONFIG":"where sas-cli stores authentication information",
+      "SSLCERT": "where you have stored the tls information(see below)",
+      "VIYACERT": "where you have stored the viya server ssl certificates for calls to Viya server",
+      "VIYA_SERVER": "viya server if AUTHFLOW=password|token|refresh",
+      "PASSWORD": "password if AUTHFLOW is password",
+      "USERNAME": "username if AUTHFLOW is password",
+      "CLIENTIDPW": "client password if AUTHFLOW is password",
+      "CLIENTSECRETPW": "client id if AUTHFLOW is password",
+      "TOKENFILE": "file if AUTHFLOW is token",
+      "COMPUTECONTEXT": "SAS Job Execution compute context",
+      "CASSERVER": "cas-shared-default",
+    }
+  }
+
+```
+
+### http transport
+
+This is an alternate to using stdio.
+This requires the .env file, which has the necessary configuration values described earlier in this document.
+It also requires the MCP server to be running (see step 2).
+
+> Remote MCP servers: This is under development
+
+#### Step 1: Configure the mcp client for localhost
+
+The mcp configuration is show below
+
+```json
+ "sasmcp": {
+    "type": "http",
+    "url": "http(s)//localhost:8080/mcp"``
+ }
+```
+
+Here is a typical .env file for http transport
+
+```env
+
+PORT=8080
+HTTPS=FALSE
+MCPTYPE=http
+VIYA_SERVER=https://myviya.com
+AUTHFLOW=sascli
+SAS_CLI_PROFILE=00m
+SAS_CLI_CONFIG=c:\Users\<yourusername>
+SSLCERT=c:\Users\yourusername\.tls 
+VIYACERT=c:\Users\yourusername\viyaCert
+CAS_SERVER=cas-shared-default
+COMPUTECONTEXT=SAS Job Execution compute context
+
+```
+Use https if the environment variables HTTPS=TRUE
+
+
+#### Step 2: Start the mcp server
+
+If using stdio transport, most of the mcp clients will start the server automatically.
+But this step is necessary of using http transport.
+
+
+```sh
+npx dotenv-cli -e .env -- npx @sassoftware/sas-app-mcp-serverjs@latest
+```
+
+An alternative to using dotenv-cli is to preset the environment variables.
+Make sure that the .env file is in the current working directory
+
+
+## Notes
+
+The mcp server caches information for each mcp session id(user). 
+
+However, cas and compute sessions are not cached in this release(TBD).
+The implication of this design choice is felt most when the tool needs is creating compute session * the requests will take longer than when the compute session is cached.
+
+## Other Useful Tips
+
+### mkcert
+To create a self-signed certificate for localhost:
+
+```sh
+mkcert -install
+```
+
+The install also stores local root Certificate Authority (CA) on the system.
+For windows the location is `AppData/Local\mkcert`.
+
+Now go to the location where you want to store the certificates.
+Then create the certificates:
+
+```sh
+mkcert -key-file key.pem -cert-file crt.pem localhost 127:0.0.1 ::1
+```
+
+One last step for windows nodejs users.
+Add this to the environment variable `NODE_EXTRA_CA_CERTS`:
+
+```text
+NODE_EXTRA_CA_CERTS=c:\Users\<your_username>\AppData\Local\mkcert\rootCA.pem
+```
+
+## License
+This project is licensed under the [Apache 2.0 license](LICENSE).
+
+## Additional Resources
+
+* [Documentation on modelcontextprotocol(mcp)](https://modelcontextprotocol.io/introduction)
+* [mcp sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
+* [restaf](https://sassoftware.github.io/restaf/)
+* [mkcert](https://www.npmjs.com/package/mkcert)
+* [SAS tokens](https://communities.sas.com/t5/SAS-Communities-Library/SAS-Viya-CLI-Token-Expiry/ta-p/848183)
+* Also see <https://communities.sas.com> for articles on using mcp servers with SAS Viya

package/SECURITY.md

@@ -0,0 +1,31 @@
+<!-- 
+A SECURITY.md outlines your project's security policy. It includes instructions on how to report a security vulnerability in your project.
+If your project contains this file, link to it from the project's README. 
+-->
+
+# PROJECT_NAME Security Policy
+<!-- Replace PROJECT_NAME with the official name of your SAS-sanctioned open source project. -->
+Project maintainers and community contributors take security issues seriously.
+Efforts to disclose potential issues responsibly are appreciated, and viable contributions will be acknowledged. 
+To aid investigation of any reported vulnerabilities, please follow the [reporting guidelines](#reporting-guidelines) when submitting your findings.
+
+## Reporting Guidelines
+<!-- Project maintainers: Activate GitHub's built-in private reporting:
+
+https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository
+-->
+
+To report a suspected security issue, use private vulnerability reporting.
+
+1. Click the `Security` tab
+1. Click the `Report a vulnerability` button
+
+Then provide the following information with suspected security issues:
+
+* Your name and affiliation
+* Version/build-date of project 
+* Issue description
+* Steps to reproduce the issue
+* Current public knowledge of this vulnerability (for example, related CVE, security advisory, and so on), if known
+
+The project release notes contain acknowledgments for contributors who provide security-related insights in their commits.

package/SUPPORT.md

@@ -0,0 +1,3 @@
+## Support
+Project maintainers use GitHub for tracking bugs and feature requests.
+Please submit a GitHub issue or pull request for support.