0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/templates/template-company-knowledge
Justin Levine db417615a8
feat(templates): use Mastra Connect in the company knowledge template (#29745)
## Description

The company knowledge template now reads Linear and Notion through the
project's Mastra Connect connections instead of `LINEAR_API_KEY` and
`NOTION_API_KEY`. That way, deploying it from Mastra Platform no longer
asks for provider keys. The chat model comes from `AGENT_MODEL` and
defaults to the current Gateway model, so Platform can set it per
project later. Web search uses the Gateway web search tool from
docs-expert, so it works on any model. When a project has more than one
Linear or Notion account connected, indexing covers each one.

```diff
- mcp.ts: MCPClient for mcp.linear.app + @notionhq/notion-mcp-server, keyed by env vars
+ connect.ts: tools({ providers: ['linear', 'notion'] }) when MASTRA_PLATFORM_ACCESS_TOKEN + MASTRA_PROJECT_ID are set
- index-knowledge: raw Linear GraphQL + Notion REST with API keys
+ index-knowledge: linear_list_issues, notion_search_pages, notion_get_page_as_markdown via Connect, per connection
- openai.tools.webSearch (OpenAI models only)
+ tools/web-search.ts (Gateway, any model)
```

## Related issue(s)

Linear PLTFRM-3311. After merge, the template's Platform settings drop
the three env vars and list Linear and Notion as integrations.

## Type of change

- [x] New feature (non-breaking change that adds functionality)

## Checklist

- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

Verified: `mastra build` passes and `tsc` is clean against the published
packages. Not run against real Linear and Notion connections yet.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## ELI5

The template now gets Linear and Notion data through connections in a
Mastra project, instead of asking users for separate service keys. It
also uses Mastra Gateway for web searches and lets users choose the
agent’s model.

## Changes

- Added Mastra Connect tools for Linear and Notion. They load when
platform credentials and a project ID are configured.
- Updated indexing to fetch Linear issues and Notion pages through those
connections.
- Added a Gateway-backed web search tool and an optional `AGENT_MODEL`
setting. The default agent model is `mastra/openai/gpt-5.4`.
- Updated setup documentation and dependencies. Removed the previous MCP
configuration and direct-service API key setup.

## Tests

Build and test results: not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
History 2026-11-09 18:02:19 +00:00
..
src/mastra feat(templates): use Mastra Connect in the company knowledge template (#29745) 2026-11-09 18:02:19 +00:00
.env.example feat(templates): use Mastra Connect in the company knowledge template (#29745) 2026-11-09 18:02:19 +00:00
.gitignore feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00
package.json feat(templates): use Mastra Connect in the company knowledge template (#29745) 2026-11-09 18:02:19 +00:00
README.md feat(templates): use Mastra Connect in the company knowledge template (#29745) 2026-11-09 18:02:19 +00:00
tsconfig.json feat(templates): New templates showcasing latest Mastra features (#17425) 2026-06-16 12:26:14 -04:00

Company Knowledge Agent

Indexes your Linear issues and Notion pages into pgvector (on Neon) and exposes a single agent that answers questions over them. The agent searches the indexed corpus first, falls back to live Linear/Notion lookups through Mastra Connect, and uses Gateway-backed web search as a last resort.

A scheduled workflow (index-knowledge) re-indexes every 6 hours automatically. Input is normalized with UnicodeNormalizer, and PIIDetector redacts emails, phone numbers, SSNs, credit card numbers, and API keys from responses before they reach the user.

Prerequisites

  • Node.js >= 22.13.0
  • A Neon Postgres database (or any Postgres 11+ with the vector extension)
  • A Gateway API key — get one at gateway.mastra.ai
  • A Mastra platform project with a Linear and/or Notion connection attached, and an access token for it

Setup

pnpm install
cp .env.example .env
# fill in MASTRA_GATEWAY_API_KEY, DATABASE_URL, MASTRA_PLATFORM_ACCESS_TOKEN, MASTRA_PROJECT_ID
pnpm dev

On Neon, make sure CREATE EXTENSION IF NOT EXISTS vector; has been run on your database.

Indexing your knowledge base

Run the index-knowledge workflow from Mastra Studio (pnpm dev → workflows tab) or programmatically. It will:

  1. Pull up to N recent Linear issues through the project's Linear connection.
  2. Search Notion pages the Notion connection can see, and read each one as markdown.
  3. Embed each document with mastra/openai/text-embedding-3-small through the Gateway.
  4. Upsert into the company_knowledge pgvector index.

The workflow is scheduled to run every 6 hours automatically. You can also trigger it manually from Studio or programmatically.

How the agent answers

The agent's instructions force this order:

  1. search-knowledge — semantic search over the indexed corpus.
  2. Live Linear / Notion tools (via Mastra Connect) — when fresh data is needed.
  3. Gateway-backed web_search — for public information. Search uses a separate model through the Gateway, so it remains available regardless of the agent's AGENT_MODEL.

Sources (URLs) are always cited in the response.

Environment variables

Variable Purpose
MASTRA_GATEWAY_API_KEY Routes the chat model, embeddings, and provider tools through the Gateway.
DATABASE_URL Neon (or other) Postgres connection string with ?sslmode=require.
MASTRA_PLATFORM_ACCESS_TOKEN Mastra platform access token, used by Mastra Connect.
MASTRA_PROJECT_ID The Mastra platform project whose Linear and Notion connections are used.
AGENT_MODEL Optional model router id. Defaults to mastra/openai/gpt-5.4.

Agent Editor

This template enables the code-backed Agent Editor with new MastraEditor({ source: 'code', codePath: 'mastra/editor' }). Edits made in Studio are written as deterministic JSON overrides under mastra/editor/agents/, so Mastra Platform can open GitHub pull requests for agent changes instead of only saving them to the database.