sap-cap-capire

SAP CAP-Capire 開発スキル

関連スキル

• sap-fiori-tools：UI レイヤーの開発、Fiori Elements の統合、フロントエンドアプリケーションの生成に使用します
• sapui5：カスタム UI の開発、高度な UI パターン、フリースタイルアプリケーションの構築に使用します
• sap-btp-cloud-platform：デプロイオプション、Cloud Foundry／Kyma の設定、BTP サービスの統合に使用します
• sap-hana-cli：データベース管理、スキーマの調査、HDI コンテナの管理に使用します
• sap-abap：ABAP システムとの統合、外部サービスの利用、SAP 拡張に使用します
• sap-btp-best-practices：本番環境へのデプロイパターンとアーキテクチャに関するガイダンスに使用します
• sap-ai-core：CAP アプリケーションに AI 機能を追加する場合や、SAP AI サービスと統合する場合に使用します
• sap-cloud-sdk-ai：CAP イベントハンドラーでの SDK レベルの AI 統合（チャット補完、ストリーミング、ツール呼び出し）に使用します
• sap-cloud-sdk-ai-python：CAP Java またはスタンドアロンの BTP サービスでの Python ベースの AI 統合に使用します
• sap-api-style：CAP OData サービスを文書化する場合や、API ドキュメントの標準に準拠する場合に使用します
• sap-dependency-security：CAP サービスリポジトリにおける依存関係、ロックファイル、サプライチェーンのセキュリティ、および MCP サーバーの厳密なバージョン固定の管理に使用します

このスキルを使用する場面

CAP プロジェクトの作成、CDS エンティティ／サービスのモデリング、Node.js または Java イベントハンドラーの実装、HANA／SQLite／PostgreSQL の永続化設定、BTP Cloud Foundry または Kyma へのデプロイ、Fiori UI の追加、認可／マルチテナント／メッセージングの設定、または CAP MCP／LSP ツールの使用時に、このスキルを使用します。

よくある問題

問題	最初に確認すること
cds watch または cds serve が失敗する	@sap/cds-dk、Node.js のバージョン、プロジェクトの package.json スクリプトを確認します。
エンティティ／サービスが見つからない	利用可能な場合は CAP MCP search_model を使用し、その後 db/ と srv/ の CDS ファイルを調べます。
HANA へのデプロイが失敗する	HDI サービスバインディング、mta.yaml、HANA のデプロイ参照を確認します。
認可が想定どおりに動作しない	@requires、@restrict、XSUAA／IAS バインディング、ユーザーロールのマッピングを確認します。

目次

• クイックスタート
• プロジェクト構成
• 主要な概念
• AI 統合
• データベースの設定
• デプロイ
• 同梱リソース

クイックスタート

プロジェクトの初期化

# Use an approved CAP toolchain:
# - project-local devDependencies
# - user-local npm prefix
# - enterprise-managed Node/CAP installation
# Ensure cds and optional cds-lsp commands are on PATH.
cds --version

# Create new project
cds init <project-name>
cds init <project-name> --add sample,hana

# Start development server with live reload
cds watch

# Add capabilities
cds add hana          # SAP HANA database
cds add sqlite        # SQLite for development
cds add xsuaa         # Authentication
cds add mta           # Cloud Foundry deployment
cds add multitenancy  # SaaS multitenancy
cds add typescript    # TypeScript support

基本的なエンティティの例

using { cuid, managed } from '@sap/cds/common';

namespace my.bookshop;

entity Books : cuid, managed {
  title       : String(111) not null;
  author      : Association to Authors;
  stock       : Integer;
  price       : Decimal(9,2);
}

entity Authors : cuid, managed {
  name        : String(111);
  books       : Association to many Books on books.author = $self;
}

基本的なサービス

using { my.bookshop as my } from '../db/schema';

service CatalogService @(path: '/browse') {
  @readonly entity Books as projection on my.Books;
  @readonly entity Authors as projection on my.Authors;
  
  @requires: 'authenticated-user'
  action submitOrder(book: Books:ID, quantity: Integer) returns String;
}

MCP 統合

このスキルは公式 CAP MCP（Model Context Protocol）サーバーと統合されており、AI エージェントがプロジェクトでコンパイルされた CDS モデルと CAP ドキュメントにリアルタイムでアクセスできます。

利用可能な MCP ツール：

• search_model - コンパイル済み CSN モデル内の CDS エンティティ、サービス、アクション、関連をあいまい検索します
• search_docs - 構文、パターン、ベストプラクティスについて、CAP ドキュメントをセマンティック検索します

主なメリット：

• モデルを即座に発見：ファイルを読まずに、プロジェクトのエンティティ、関連、サービスを検索できます
• コンテキストに応じたドキュメント検索：キーワードではなくセマンティックな類似性に基づいて、関連する CAP ドキュメントを見つけられます
• 設定不要：認証情報や環境変数は必要ありません
• オフラインで利用可能：すべての検索はローカル（モデル）またはキャッシュ済み（ドキュメント）です

セットアップ：Claude Code、opencode、または GitHub Copilot での設定については、MCP 統合ガイドを参照してください。MCP パッケージのバージョン固定は sap-dependency-security によって管理され、npm run validate:mcp-security で検証されます。

ユースケース：リポジトリで検証済みの ROI ではなく、ローカルでのワークフロー例と計画上の前提については、MCP のユースケースを参照してください。

エージェント統合：専用エージェント（cap-cds-modeler、cap-service-developer、cap-project-architect、cap-performance-debugger）は、ワークフローの一環としてこれらの MCP ツールを自動的に使用します。

CAP MCP と LSP によるルーティング

ローカルモデルやドキュメントに関する質問には、まず MCP を使用し、MCP が利用できない場合は直接ファイルを検索してください。長い CAP ガイドを読み込む前に、rg -n "<entity|service|aspect|annotation|handler|cds compile|deployment>" references/*.md srv db app を使って、最も関連性の高い参照を特定してください。

• MCP の設定とパッケージの固定バージョンの確認には、references/mcp-integration.md を使用してください。
• ワークフローの選択と影響の例示に限り、references/mcp-use-cases.md を使用してください。
• CAP のエディター連携には、Claude と互換性のあるサイドカーとして .lsp.json を使用してください。他のハーネスでは、自動的に読み込まれると想定しないでください。
• Codex、OpenCode、エディター、その他の LSP 対応クライアントでは、コマンドを node <sap-cap-capire-plugin-root>/lsp/cds-lsp-launcher.mjs --stdio として手動で設定してください。この場合も、承認済みのプロジェクトローカルな devDependency、ユーザーローカルな npm プレフィックス、または企業管理のツールチェーンを通じて @sap/cds-lsp をインストールし、cds-lsp を PATH から利用できるようにする必要があります。
• LSP 連携がない場合は、Markdown のガイダンス、バンドルされた参照資料、rg、CAP CLI のチェックを直接使用してください。
• 対象プロジェクトまたはテナントの証拠がない場合、稼働中のデプロイ、HANA、XSUAA、マルチテナントの検証は保留として扱ってください。

プロジェクト構造

project/
├── app/              # UI content (Fiori, UI5)
├── srv/              # Service definitions (.cds, .js/.ts)
├── db/               # Data models and schema
│   ├── schema.cds    # Entity definitions
│   └── data/         # CSV seed data
├── package.json      # Dependencies and CDS config
└── .cdsrc.json       # CDS configuration (optional)

基本概念

CDS 組み込み型

CDS 型	SQL マッピング	一般的な用途
UUID	NVARCHAR(36)	主キー
String(n)	NVARCHAR(n)	テキストフィールド
Integer	INTEGER	整数
Decimal(p,s)	DECIMAL(p,s)	金額
Boolean	BOOLEAN	真偽値
Date	DATE	暦日
Timestamp	TIMESTAMP	日時

一般的なアスペクト

using { cuid, managed, temporal } from '@sap/cds/common';
// cuid = UUID key
// managed = createdAt, createdBy, modifiedAt, modifiedBy
// temporal = validFrom, validTo

イベントハンドラー（Node.js）

// srv/cat-service.js
module.exports = class CatalogService extends cds.ApplicationService {
  init() {
    const { Books } = this.entities;
    
    // Before handlers - validation
    this.before('CREATE', Books, req => {
      if (!req.data.title) req.error(400, 'Title required');
    });
    
    // On handlers - custom logic
    this.on('submitOrder', async req => {
      const { book, quantity } = req.data;
      // Custom business logic
      return { success: true };
    });
    
    return super.init();
  }
}

基本的な CQL クエリ

const { Books } = cds.entities;

// SELECT with conditions
const books = await SELECT.from(Books)
  .where({ stock: { '>': 0 } })
  .orderBy('title');

// INSERT
await INSERT.into(Books)
  .entries({ title: 'New Book', stock: 10 });

// UPDATE
await UPDATE(Books, bookId)
  .set({ stock: { '-=': 1 } });

AI 連携

CAP アプリケーションは、SAP Cloud SDK for AI を介して SAP AI Core と連携します。推奨されるパターンでは、CAP イベントハンドラーを通じて Orchestration Service を使用し、すべての認証情報の管理を BTP サービスバインディングに任せます。

サービスバインディング（MTA）

resources:
  - name: my-ai-core
    type: org.cloudfoundry.managed-service
    parameters:
      service: aicore
      service-plan: extended

ローカル開発（ハイブリッドモード）

cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid

イベントハンドラーパターン（Node.js/TypeScript）

import { OrchestrationClient } from '@sap-ai-sdk/orchestration';

module.exports = class AnalysisService extends cds.ApplicationService {
  async init() {
    const { Feedback } = this.entities;

    this.on('analyzeFeedback', async (req) => {
      const userText = req.data.text;

      const client = new OrchestrationClient({
        promptTemplating: {
          model: { name: 'gpt-4o' },
          prompt: [
            { role: 'system', content: 'Categorize feedback as JSON: sentiment, category, urgency.' },
            { role: 'user', content: '{{?userText}}' }
          ]
        }
      });

      const response = await client.chatCompletion({
        placeholderValues: { userText }
      });

      const aiResult = response.getContent();

      await INSERT.into('FeedbackResults').entries({
        originalText: userText,
        analysisJson: aiResult
      });

      return aiResult;
    });

    return super.init();
  }
};

非同期処理（本番環境向けパターン）

LLM の呼び出しには 30〜60 秒かかることがあります。本番環境では、決して同期的に処理しないでください。LLM が応答する前に、BTP ロードバランサーがタイムアウトします。

this.on('analyzeFeedback', async (req) => {
  const id = await INSERT.into('FeedbackResults').entries({
    originalText: req.data.text,
    status: 'processing'
  });

  cds.spawn(() => processWithLLM(id, req.data.text));

  return req.reply(202, { id, status: 'processing' });
});

async function processWithLLM(id, text) {
  const response = await client.chatCompletion({
    placeholderValues: { userText: text }
  });
  await UPDATE('FeedbackResults', id).set({
    analysisJson: response.getContent(),
    status: 'completed'
  });
}

RAG 用 HANA ベクター型

entity Documents {
  key id    : UUID;
  content   : String(5000);
  embedding : Vector(1536);
}

これを HANA Cloud Vector Engine および AI Core orchestration grounding と組み合わせることで、CAP のデータモデル内に RAG シナリオを直接構築できます。

プロンプトの外部化

イベントハンドラーにプロンプトをハードコードしないでください。再デプロイせずに更新できるよう、JSON ファイルまたは CDS の設定エンティティに保存してください。

entity PromptTemplates {
  key id       : UUID;
  name         : String(100);
  systemPrompt : LargeString;
  updatedBy    : String;
  modifiedAt   : Timestamp;
}

メモリとデプロイ

大きなテキストペイロードを処理する AI SDK を使用する Node.js コンテナには、MTA ディスクリプターで少なくとも 512MB のメモリが必要です。AI SDK と JSON ペイロードの処理では、一般的な CAP サービスより多くのメモリを消費します。

SDK のドキュメント全体については、sap-cloud-sdk-ai スキルを参照してください。AI Core プラットフォームのセットアップとオーケストレーションの設定については、sap-ai-core スキルを参照してください。

データベースのセットアップ

開発（SQLite）

// package.json
{
  "cds": {
    "requires": {
      "db": {
        "[development]": { 
          "kind": "sqlite", 
          "credentials": { "url": ":memory:" } 
        },
        "[production]": { "kind": "hana" }
      }
    }
  }
}

本番環境（SAP HANA）

cds add hana
cds deploy --to hana

初期データ（CSV）

• ファイルの場所：db/data/my.bookshop-Books.csv
• 形式：<namespace>-<EntityName>.csv
• デプロイ時に自動的に読み込まれます

デプロイ

Cloud Foundry

# Add CF deployment support
cds add hana,xsuaa,mta,approuter

# Build and deploy
npm install --package-lock-only
mbt build
cf deploy mta_archives/<project>_<version>.mtar

マルチテナント（SaaS）

cds add multitenancy

設定：

{
  "cds": {
    "requires": {
      "multitenancy": true
    }
  }
}

認可の例

// Service-level
@requires: 'authenticated-user'
service CatalogService { ... }

// Entity-level
@restrict: [
  { grant: 'READ' },
  { grant: 'WRITE', to: 'admin' }
]
entity Books { ... }

バンドルされたリソース

リファレンスドキュメント（22 ファイル）

1. references/annotations-reference.md - UI アノテーションの完全なリファレンス（10K 行）
2. references/cdl-syntax.md - CDL 構文の完全なリファレンス（503 行）
3. references/cql-queries.md - CQL クエリ言語ガイド
4. references/csn-cqn-cxn.md - Core Schema Notation とクエリ API
5. references/data-privacy-security.md - GDPR とセキュリティの実装
6. references/databases.md - データベースの構成とデプロイ
7. references/deployment-cf.md - Cloud Foundry のデプロイの詳細
8. references/event-handlers-nodejs.md - Node.js イベントハンドラーのパターン
9. references/extensibility-multitenancy.md - SaaS マルチテナントの実装
10. references/fiori-integration.md - Fiori Elements と UI の統合
11. references/java-runtime.md - Java ランタイムのサポート
12. references/localization-temporal.md - i18n と時間データ
13. references/nodejs-runtime.md - Node.js ランタイムのリファレンス
14. references/plugins-reference.md - CAP プラグインと拡張機能
15. references/tools-complete.md - CLI ツールの完全なリファレンス
16. references/consuming-services-deployment.md - サービス消費のパターン
17. references/service-definitions.md - サービス定義のパターン
18. references/event-handlers-patterns.md - イベント処理のパターン
19. references/cql-patterns.md - CQL の使用パターン
20. references/cli-complete.md - CLI の完全なリファレンス
21. references/mcp-integration.md - MCP サーバーの設定と使用ガイド (新規)
22. references/mcp-use-cases.md - MCP ワークフローの具体例 (新規)

テンプレート（8 ファイル）

1. templates/bookshop-schema.cds - 完全なデータモデルの例
2. templates/catalog-service.cds - サービス定義テンプレート
3. templates/fiori-annotations.cds - UI アノテーションの例
4. templates/mta.yaml - マルチターゲットアプリケーション記述子
5. templates/package.json - プロジェクト設定テンプレート
6. templates/service-handler.js - Node.js ハンドラーテンプレート
7. templates/service-handler.ts - TypeScript ハンドラーテンプレート
8. templates/xs-security.json - XSUAA セキュリティ設定

クイックリファレンス

• CAP ドキュメント: https://cap.cloud.sap/docs/
• CDS 言語: https://cap.cloud.sap/docs/cds/
• Node.js ランタイム: https://cap.cloud.sap/docs/node.js/
• Java ランタイム: https://cap.cloud.sap/docs/java/
• ベストプラクティス: https://cap.cloud.sap/docs/about/best-practices
• GitHub リポジトリ: https://github.com/cap-js/docs

よく使う CLI コマンド

cds init [name]           # Create project
cds add <feature>         # Add capability
cds watch                 # Dev server with live reload
cds serve                 # Start server
cds compile <model>       # Compile CDS to CSN/SQL/EDMX
cds deploy --to hana      # Deploy to HANA
cds build                 # Build for deployment
cds env                   # Show configuration
cds repl                  # Interactive REPL
cds version               # Show version info

ベストプラクティス

推奨 ✓

• @sap/cds/common の cuid と managed のアスペクトを使用します
• ドメインモデルは db/ に、サービスは srv/ に、UI は app/ に配置します
• 管理アソシエーションを使用します（外部キーの処理は CAP に任せます）
• ユースケースごとに単一目的のサービスを設計します
• SQLite から始め、本番環境では HANA に切り替えます

非推奨 ✗

• SELECT * は使用せず、プロジェクションを明示します
• 生の SQL で CAP のクエリ API を迂回しないでください
• マイクロサービスを早まって作成しないでください
• 設定ファイルに認証情報をハードコードしないでください
• カスタム OData プロバイダーを作成しないでください

バージョン情報

• CAP バージョン: @sap/cds 9.7.x
• MCP バージョン: @cap-js/mcp-server 0.0.5
• LSP バージョン: @sap/cds-lsp 9.7.x
• ライセンス: GPL-3.0